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

[Simon Jakobi]

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!

So far I've made a pass over the Foldable docs. Here are some random comments:

* 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.

* 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:

  The Foldable class encompasses structures that support element-wise
reduction to a summary value.

  With words like "encompass" and "summary" (as an adjective) the
sentence sounds slightly off-putting to me – this might be a matter of
taste though.

* In the code example for computing an average, a proper declaration
might be easier to follow:

  average :: (Foldable f, Fractional a) => f a -> a

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

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

Cheers!
Simon

Am Mi., 23. Dez. 2020 um 09:20 Uhr schrieb Viktor Dukhovni
<ietf-dane at dukhovni.org>:
>
> > On Dec 20, 2020, at 8:15 PM, Viktor Dukhovni <ietf-dane at dukhovni.org> wrote:
> >
> > I am asking because I am writing some expository prose for
> > Data.Foldable, to go at the bottom of the document, structurally along
> > the lines of what I contributed for Data.Traversable, but with a fairly
> > different focus.  The goal is draw careful distinctions between
> > strict recursive and lazy corecursive reductions, explaining their
> > proper usage and typical implementations.
>
> The draft version can be seen at:
>
>   https://imrryr.org/~viktor/haskell/foldable-doc/Data-Foldable.html
>
> along with a pre-formatted Data.Traversable (already merged some
> months back, but may not yet be easy to found in formatted form):
>
>   https://imrryr.org/~viktor/haskell/foldable-doc/Data-Traversable.html
>
> Any feedback appreciated... Is this roughly ready for an MR, or are there
> any changes that are needed first and best discussed on the list rather
> than via Gitlab?
>
> --
>         Viktor.
>
> _______________________________________________
> Libraries mailing list
> Libraries at haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/libraries