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

In the "lazy corecursive" section from your original links, you mention a "flatten" function, but then the next function is named "toList". I think this might be an oversight. ======= Georgi

On Dec 24, 2020, at 7:22 PM, Viktor Dukhovni wrote:

If the overall approach is sound, it might perhaps now make sense to add some brief text also in each function synopsis that classifies it as strict recursive, lazy corecursive, or some hybrid. But perhaps just having that level of detail at the bottom is sufficient?

I've forked the document to explore carving out a third-class of folds, the *short-circuit* folds, that though they also are based on `foldr`, are not really corecursive, they just might terminate early, but produce only a single final result. This variant is at: <https://imrryr.org/~viktor/haskell/foldable-doc/Data-Foldable-v2.html The original is at: https://imrryr.org/~viktor/haskell/foldable-doc/Data-Foldable.html Is the new version heading in the right direction? Is anyone interested in helping out to get the initial draft in good enough shape for an MR? -- Viktor.

On Sun, Dec 27, 2020 at 11:20:00AM +0100, Ben Franksen wrote:

...

This variant is at: <https://imrryr.org/~viktor/haskell/foldable-doc/Data-Foldable-v2.html The original is at: https://imrryr.org/~viktor/haskell/foldable-doc/Data-Foldable.html

Is the new version heading in the right direction? Is anyone interested in helping out to get the initial draft in good enough shape for an MR?

One minor nitpick:

Short-circuit reduction, which examines some initial sequence of the input elements, but stops once a termination condition is met, returning a final result based only on the elements considered to that point. The ^ up

This one should really be fixed:

remaining elements are not considered. The input should generally be finite, because the termination condition but otherwise be never met. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ hard to understand because of grammar mistakes

Otherwise: very well written.

Thanks, while reworking it, some things gone mangled, and I haven't finished the proofreading yet. I'll fix these pronto.

Why are the class laws part of the Overview and not of the class documentation proper as usual?

Good question. My take is that the typical *user* of the library is not generally immediately interested in the laws, and so I prefer to present the function synopses as quickly as possible up front. For the more sophisticated users who'll be implementing instances, the laws are are in their own section, with a link from the index at the top, an not buried in the middle of the topmatter. -- Viktor.

On Sun, Dec 27, 2020 at 05:47:46AM -0500, Viktor Dukhovni wrote:

With a bit of luck (for this MR), given the delay in GHC 9.0, perhaps it could even make it into the GHC 9.0 release.

I went ahead and opened in MR: https://gitlab.haskell.org/ghc/ghc/-/merge_requests/4689 -- Viktor.