Move the docstrings

[mcabbott]

The docstrings are much longer than the actual code. I guess I like them long since I extended many of them, but they do get in the way of finding the function body. So this moves them out to the main file, which is otherwise just 3 lines.

No functional change.

[mcabbott]

Maybe more controversial, but I'd also like to move code around in the main file. I think it would much easier to read if it was ordered:

• The basic stuff, up to fmap, 50 lines
• The extras, like fcollect
• The vararg extensions
• FlexibleFunctors

(Not yet pushed.)

[darsnack]

Good idea. Maybe just put them in a docstrings.jl or interfaces.jl file instead of the main one?

[mcabbott]

Ok, pushed. This will trash git blame, but so be it.

Now that I understand it, the 50-line core is actually quite pretty. Maybe I was confused by how much of the auxiliary stuff it was necessary to understand, and by trying to puzzle out docstrings & names for things, not what they do.

[ToucheSir]

I still stand by #32 (comment), namely that the prettiness comes at a pretty significant cost. That said, this is a genuine QoL improvement for working on the code, as it saves having to jump around too much.

[mcabbott]

Good to go?

Putting these in the main file isn't a pattern I've seen, and maybe we will hate it later. But Optimisers.jl does this and it doesn't seem awful. If you don't know the package, then you have to open the file to find out that it has nothing but two includes; and this way, you now also know where the docstrings are. This seems neater to me than needing another top-level file.

[ToucheSir]

Another model I've seen is having the docstrings in external markdown files and attaching them. ConstructionBase does this: https://github.com/JuliaObjects/ConstructionBase.jl/blob/master/src/ConstructionBase.jl#L8