Expanding Data.Foldable documentation with overview prose (pre-MR feedback requested)

[Viktor Dukhovni]

On Thu, Dec 24, 2020 at 05:25:34AM +0100, Simon Jakobi via Libraries wrote:

> Hi Victor!
> 
> Thanks for this initiative! I think it would be great to have some
> good, in-depth documentation on Foldable and Traversable in base!

Thanks for the encouragement.  FWIW, the Traversable writeup (module a
reference URL update), is already in base (for 9.0), but if you find
things worth fixing, there may yet be time to get some of those done.

> * I think the docs at the bottom of the page are easy to miss. Maybe
> add a reference to them at the top of the page.

Done.

> * I think the documentation might be more accessible and inviting if
> it would use slightly simpler language. For example the first sentence
> of the overview section:

I made some effort to simplify the language.  I hope it is better.

> * In the code example for computing an average, a proper declaration
> might be easier to follow:
> 
>   average :: (Foldable f, Fractional a) => f a -> a

Done.

> * A clearer name for the "Construction" section might be "Defining instances"

Done.  Thanks.

> * The distinction between recursive and corecursive reduction looks
> very valuable IMHO!

I'm glad you like it.  For me, writing this down was actually the main
motivation for the new text.  I wanted to understand it better, and this
seemed like the best way. :-)

Let me know when you think this is close enough to being ready to move
the final polish discussion to Gitlab.

-- 
    Viktor.