macro docstring, incl. hcat(3.3)

Author: mcabbott

src/layers/macro.jl

@@ -10,34 +10,35 @@ When you define a new layer, this tells Flux to explore inside it
 to see the parameters it trains, and also to move them to the GPU, change precision, etc.
 Like `@functor`, this assumes your struct has the default constructor, to enable re-building.
 
-Some "keywords" allow control of the recursion. 
+Some keywords allow you to limit this exploration, instead of visiting all `fieldnames(T)`.
+Note that it is never necessary to tell Flux to ignore non-array objects such as functions or sizes.
 * If some fields look like parameters but should not be trained,
-  then `trainable` lets you specify fields to include, and ignore the rest.
-* You can likewise add restructions to Functors's `children` (although this is seldom a good idea).
+  then `trainable` lets you specify which fields to include, while the rest are ignored.
+* You can likewise add restrictions to Functors's `children` (although this is seldom a good idea),
+  equivalent to `@functor Struct (α,β)`. Any `trainable` limitation must then be a subset of `children`.
 
-The defaults are `fieldnames(T)` for both. They must be subsets of this, and `trainable` must be a subset of `children`.
-
-It also handles overloads of `show` for pretty printing.
+The macro also handles overloads of `show` for pretty printing.
 * By default, it adds methods to 3-arg `Base.show` to treat your layer much like `Dense` or `Conv`.
 * If your layer is a container, more like `Chain` or `Parallel`, then `:expand` makes `show` unfold its contents.
 * To disable all `show` overloads, there is an `:ignore` option too.
 
-Note that re-running the macro with different options does not overwrite all methods, you will need to restart.
 (You probably still want to define 2-arg `show(io::IO, x::Layer)`, the macro does not touch this.)
 
+Note that re-running the macro with different options may not overwrite all methods, you will need to restart.
+
 # Example
 ```jldoctest
 julia> struct Trio; a; b; c end
 
-julia> tri = Trio(Dense([1.1 2.2], [0.0], tanh), Dense([3.3;;], false), Dropout(0.4))
+julia> tri = Trio(Dense([1.1 2.2], [0.0], tanh), Dense(hcat(3.3), false), Dropout(0.4))
 Trio(Dense(2 => 1, tanh), Dense(1 => 1; bias=false), Dropout(0.4))
 
 julia> Flux.destructure(tri)  # parameters are not yet visible to Flux
 (Bool[], Restructure(Trio, ..., 0))
 
 julia> Flux.@layer :expand Trio
 
-julia> Flux.destructure(tri)  # now gpu, train!, etc will see inside too
+julia> Flux.destructure(tri)  # now gpu, params, train!, etc will see inside too
 ([1.1, 2.2, 0.0, 3.3], Restructure(Trio, ..., 4))
 
 julia> tri  # and layer is printed like Chain