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

[Viktor Dukhovni]

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.