docs

Author: CarloLucibello

Project.toml

@@ -5,19 +5,16 @@ version = "0.4.4"
 
 [deps]
 ConstructionBase = "187b0558-2788-49d3-abe0-74a17ed4e7c9"
-Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 
 [compat]
 ConstructionBase = "1.4"
-Documenter = "0.27"
 julia = "1.6"
 
 [extras]
-Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f"
 
 [targets]
-test = ["Test", "Documenter", "StaticArrays", "Zygote"]
+test = ["Test", "StaticArrays", "Zygote"]

docs/src/index.md

@@ -8,9 +8,9 @@ For large models it can be cumbersome or inefficient to work with parameters as
 
 ## Basic Usage and Implementation
 
-When one marks a structure as [`@functor`](@ref) it means that Functors.jl is allowed to look into the fields of the instances of the struct and modify them. This is achieved through [`Functors.fmap`](@ref).
+By default, julia types are marked as [`@functor`](@ref)s, meaning that Functors.jl is allowed to look into the fields of the instances of the struct and modify them. This is achieved through [`Functors.fmap`](@ref).
 
-The workhorse of fmap is actually a lower level function, functor:
+The workhorse of `fmap` is actually a lower level function, functor:
 
 ```julia-repl
 julia> using Functors
@@ -20,8 +20,6 @@ julia> struct Foo
          y
        end
 
-julia> @functor Foo
-
 julia> foo = Foo(1, [1, 2, 3]) # notice all the elements are integers
 
 julia> xs, re = Functors.functor(foo)
@@ -50,12 +48,17 @@ julia> fmap(float, model)
 Baz(1.0, 2)
 ```
 
-Any field not in the list will be passed through as-is during reconstruction. This is done by invoking the default constructor, so structs that define custom inner constructors are expected to provide one that acts like the default.
+Any field not in the list will be passed through as-is during reconstruction. This is done by invoking the default constructor accepting all fields as arguments, so structs that define custom inner constructors are expected to provide one that acts like the default. 
 
-## Appropriate Use
+The use of `@functor` with no fields argument as in `@functor Baz` is equivalent to `@functor Baz fieldnames(Baz)`
+and also equivalent to avoiding `@functor` altogether.
+
+Using [`@leaf`](@ref) instead of [`@functor`](@ref) will prevent the fields of a struct from being traversed. 
 
-!!! warning "Not everything should be a functor!"
-    Due to its generic nature it is very attractive to mark several structures as [`@functor`](@ref) when it may not be quite safe to do so.
+!!! warning "Change to opt-out behaviour in v0.5"
+    Previous releases of functors, up to v0.4, used an opt-in behaviour where structs were not functors unless marked with `@functor`. This was changed in v0.5 to an opt-out behaviour where structs are functors unless marked with `@leaf`.
+
+## Appropriate Use
 
 Typically, since any function `f` is applied to the leaves of the tree, but it is possible for some functions to require dispatching on the specific type of the fields causing some methods to be missed entirely.
 

src/Functors.jl

@@ -40,8 +40,6 @@ this can be restricted be restructed by providing a tuple of field names.
 ```jldoctest
 julia> struct Foo; x; y; end
 
-julia> @functor Foo
-
 julia> Functors.children(Foo(1,2))
 (x = 1, y = 2)
 
@@ -50,6 +48,8 @@ julia> _, re = Functors.functor(Foo(1,2));
 julia> re((10, 20))
 Foo(10, 20)
 
+julia> @functor Foo # same as before, nothing changes
+
 julia> struct TwoThirds a; b; c; end
 
 julia> @functor TwoThirds (a, c)

test/runtests.jl

@@ -4,18 +4,7 @@ using LinearAlgebra
 using StaticArrays
 
 @testset "Functors.jl" begin
-
   include("basics.jl")
   include("base.jl")
   include("flexiblefunctors.jl")
-
-  # if VERSION >= v"1.7"
-  #   @warn "skipping doctests, on Julia $VERSION"
-  # else
-  #   using Documenter
-  #   @testset "doctests" begin
-  #     DocMeta.setdocmeta!(Functors, :DocTestSetup, :(using Functors); recursive=true)
-  #     doctest(Functors, manual=true)
-  #   end
-  # end
 end