[Haskell-cafe] Improving the docs (specifically Data.Foldable)

[Viktor Dukhovni]

On Fri, Oct 01, 2021 at 11:52:53AM +0200, Ben Franksen wrote:

> > Well a balanced Tree can have an efficient corecursive foldl, or a
> > performant 'foldr`', and Sets can know their size statically, and `elem`
> > runs in linear time even in structures that potentially support faster
> > search.
> 
> All true, and I think it is important to document these things. The
> question is: where?

I disagree that everything one should know about Data.Foldable is
adequately described in Data.List.  At least not without a new overview
for Data.List that would cover some of the same ground in that
specialised context, and could then be imported by reference. 

A reader who wants to better understand folds should learn the
difference between strict reduction and corecursion, and certainly
Data.List is not the best place to discuss tips for construction of
Foldable instances.

Perhaps the overview could start with a concise version that explains
thinking about folds in terms of lists, and notes quickly that one
cat typically get by with understanding "foldr", "foldl'" and foldMap.

But ultimately one should understand why foldl', how to define
instances, why `elem` is stuck doing linear lookup for `Set`, ...

Would you like to contribute the "short version" introductory text for
the impatient?

Different readers will come to the documentation for different needs,
most will come for just the synopses, and won't read the Overview,
that's fine.  If there's a need for a shorter blurb, please contribute.

Perhaps the best path forward is to get MR 6555 done and dusted, and
then additional MRs can be filed on top of that by those who'd like
to see further improvements?

-- 
    Viktor.