doc changes re at-functor and at-layer

Project.toml

@@ -1,6 +1,6 @@
 name = "Flux"
 uuid = "587475ba-b771-5e3f-ad9e-33799f191a9c"
-version = "0.14.12"
+version = "0.14.13"
 
 [deps]
 Adapt = "79e6a3ab-5dfb-504d-930d-738a2a938a0e"

docs/src/models/advanced.md

@@ -142,7 +142,7 @@ Join(combine, paths...) = Join(combine, paths)
 ```
 Notice that we parameterized the type of the `paths` field. This is necessary for fast Julia code; in general, `T` might be a `Tuple` or `Vector`, but we don't need to pay attention to what it specifically is. The same goes for the `combine` field.
 
-The next step is to use [`Functors.@layer`](@ref) to make our struct behave like a Flux layer. This is important so that calling `params` on a `Join` returns the underlying weight arrays on each path.
+The next step is to use [`Flux.@layer`](@ref) to make our struct behave like a Flux layer. This is important so that calling `params` on a `Join` returns the underlying weight arrays on each path.
 ```julia
 Flux.@layer Join
 ```

docs/src/models/basics.md

@@ -255,7 +255,7 @@ m(5) # => 26
 
 ## Layer Helpers
 
-There is still one problem with this `Affine` layer, that Flux does not know to look inside it. This means that [`Flux.train!`](@ref) won't see its parameters, nor will [`gpu`](@ref) be able to move them to your GPU. These features are enabled by the [`@functor`](@ref Functors.@functor) macro:
+There is still one problem with this `Affine` layer, that Flux does not know to look inside it. This means that [`Flux.train!`](@ref) won't see its parameters, nor will [`gpu`](@ref) be able to move them to your GPU. These features are enabled by the [`@layer`](@ref Flux.@layer) macro:
 
 ```julia
 Flux.@layer Affine

docs/src/models/functors.md

@@ -2,7 +2,11 @@
 
 Flux models are deeply nested structures, and [Functors.jl](https://github.com/FluxML/Functors.jl) provides tools needed to explore such objects, apply functions to the parameters they contain, and re-build them.
 
-New layers should be annotated using the `Functors.@functor` macro. This will enable [`params`](@ref Flux.params) to see the parameters inside, and [`gpu`](@ref) to move them to the GPU.
+!!! compat "Flux ≤ 0.14"
+    All layers used to be defined with the `Functors.@functor` macro.
+    This still works, but it is recommended that you use the new [`Flux.@layer`](@ref Flux.@layer) macro instead.
+    Both allow [`params`](@ref Flux.params) to see the parameters inside, and [`gpu`](@ref) to move them to the GPU, but [`Flux.@layer`](@ref Flux.@layer) also overloads printing,
+    and offers a way to define `trainable` at the same time.
 
 `Functors.jl` has its own [notes on basic usage](https://fluxml.ai/Functors.jl/stable/#Basic-Usage-and-Implementation) for more details. Additionally, the [Advanced Model Building and Customisation](@ref man-advanced) page covers the use cases of `Functors` in greater details.
 

docs/src/models/layers.md

@@ -12,7 +12,7 @@ The `Dense` exemplifies several features:
 
 * The bias vector is always initialised [`Flux.zeros32`](@ref). The keyword `bias=false` will turn this off, i.e. keeping the bias permanently zero.
 
-* It is annotated with [`@functor`](@ref Functors.@functor), which means that [`params`](@ref Flux.params) will see the contents, and [`gpu`](@ref Flux.gpu) will move their arrays to the GPU.
+* It is annotated with [`@layer`](@ref Flux.@layer), which means that [`params`](@ref Flux.params) will see the contents, and [`gpu`](@ref Flux.gpu) will move their arrays to the GPU.
 
 By contrast, `Chain` itself contains no parameters, but connects other layers together.
 The section on [dataflow layers](@ref man-dataflow-layers) introduces others like this.

docs/src/saving.md

@@ -16,7 +16,7 @@ julia> struct MyModel
            net
        end
 
-julia> Flux.@functor MyModel
+julia> Flux.@layer MyModel
 
 julia> MyModel() = MyModel(Chain(Dense(10, 5, relu), Dense(5, 2)));
 

src/layers/macro.jl

@@ -7,12 +7,12 @@
 This macro replaces most uses of `@functor`. Its basic purpose is the same:
 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.
+If you define an inner constructor (i.e. a function within the `struct` block) things may break.
 
 The keyword `trainable` allows 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 which fields to include, while the rest are ignored.
 
 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`.
@@ -21,7 +21,7 @@ The macro also handles overloads of `show` for pretty printing.
 
 (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.
+Note that re-running the macro with different options may not remove all methods, you will need to restart.
 
 # Example
 ```jldoctest