On Fri, Sep 17, 2021 at 11:27:12AM +0900, Michael Turner wrote:
I am also curious whether I'm part of the solution or part of the precipitate. I've recently contributed new documentation for Data.Foldable and Data.Traversable:
https://dnssec-stats.ant.isi.edu/~viktor/haskell/docs/libraries/base/Data-Fo... https://dnssec-stats.ant.isi.edu/~viktor/haskell/docs/libraries/base/Data-Tr...
OK:
"Merging the contribution of the current element with an accumulator value from a partial result is performed by an operator function, either explicitly provided by the caller as in foldr, implicit count as in length, or partly implicit as in foldMap (where each element is mapped into a Monoid, and the monoid's mappend operator performs the merge)."
Let me tell you how I tried to read that lo-o-ong sentence.
If I may trouble you just a bit longer, I'd like to ask whether the problem is the phrasing, or the selection of subject matter. If the latter, then any defects in the phrasing are perhaps moot. Supposing I rephrase the same thing as: The contribution of each element to the final result is combined with an accumulator via an /operator/ function. The operator may be explicitly provided by the caller as in `foldr` or may be implicit as in `length`. In the case of `foldMap`, the caller provides a function mapping each element into a suitable 'Monoid', which makes it possible to merge the per-element contributions via that monoid's `mappend` function. Does that help? At all? Enough? The word "Monoid" hyperlinks to the documentation of that class, and I thought it fair to reference Monoids in the reference documentation for a module that defines `foldMap`. If the above is helpful, I am not too proud to rewrite any paragraphs that are poorly phrased, if there is some merit in the subject matter. I don't think the module overview can be a beginner tutorial, that's more the domain of books, ... I think that the descriptive prose in the reference docs that follows the function synopses just need to cover any concepts and API behaviours that don't immediately follow from those synopses. A rough guide for me were Unix manpages, where e.g. setsockopt(2) is not a networking tutorial, and yet still has a bunch of useful prose, and not just function signatures. -- Viktor.