@functor needs better documentation

[freemin7]

I was studying the Flux source code how to create me own layer types.
I came across the macro @functor whose purpose remained unclear to me. After asking in Slack it was signaled to me that those question comes up a lot and that it should be answered here.

I could imagine the documentation taking these forms:

• Make really good clear examples and explanation of @functor in docs and explain when you need it and what for
• an expansion of the affine tutorial which includes @functor as opposed to functor being out of context and vague at the end of the page. The tutorial should enable the user to develop a first-class flux layer.

[DhairyaLGandhi]

Relevant FluxML/Flux.jl#1028

[HamletWantToCode]

One thing about @functor still confuse me. Inside functor's definition, e.g.

functor(x::AbstractArray) = x, y -> y

it returns a Tuple. The 2nd element of the tuple is a function, however, it seems that this function has never been used ( I searched through the repository, but just find functor(m)[1], which uses the 1st element of the returned tuple ).

So:

1. Why functor's return value include e.g. y->y ?

2. (continue the 1st) If it's necessary, where & when should we use it ?

[ToucheSir]

For anyone happening upon this issue, the Functors README has a good explanation of what's returned and what it's all used for. In this case, y -> y is the re(construct) function that allows you to "rehydrate" a structure from its constituent parts. Since arrays are considered un-destructureable base values, no logic is required to restructure them and re is just the identity function.

[CarloLucibello]

the documentation has improved a lot since then. open a new issue if something is still amiss