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

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 :

...

On Dec 20, 2020, at 8:15 PM, Viktor Dukhovni 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@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/libraries