[Haskell-cafe] Comments from OCaml Hacker Brian Hurt

[david48]

On Fri, Jan 16, 2009 at 5:39 AM, Creighton Hogg <wchogg at gmail.com> wrote:
> For you folks who work on GHC, is it acceptable to open tickets for
> poor documentation of modules in base?  I think leaving the
> documentation to the tragedy of the commons isn't the best move, but
> if even a few of us could remember to open tickets when new
> Haskell'ers complain about something being confusing then it could be
> on _someone's_ docket.

I second that.

Upon reading this thread, I asked myself : what's a monoid ? I had no
idea. I read some posts, then google "haskell monoid".

The first link leads me to Data.Monoid which starts with

<<
Description
The Monoid class with various general-purpose instances.

Inspired by the paper /Functional Programming with Overloading and
Higher-Order Polymorphism/, Mark P Jones
(http://citeseer.ist.psu.edu/jones95functional.html) Advanced School
of Functional Programming, 1995.
>>

Before going further, I click on the link and I'm on citeseer. The
abstract talks about the Hindley/Milner type system, but no mention of
monoid. I download the pdf, and search for monoid in acrobat reader.
No matches.

I read further on Data.Monoid...

<<
The monoid class. A minimal complete definition must supply mempty and
mappend, and these should satisfy the monoid laws."
>>

The laws are not mentionned. I learn that there are 3 operations on monoids:
mappend which is an associative operation
mempty which is an identity of mappend.
mconcat which "folds a list using the monoid", which I think I
understand this way : mempty will be the seed of the fold, and mappend
the fonction called for each item.

The module defines the dual of a monoid without explaining much; the
"monoid of endomorphisms under composition" (another word to look up)
In fact I realise many monoids are defined, and I don't know what are
they usefull for.

The next few pages google gives me are about monads.
Then there's some blog posts by sigfpe, which I'm not going to read
because they're often way too complicated for me to understand.
Actually I still read it and there I find what I think is a monoid law:

<<
They are traditionally sets equipped with a special element and a
binary operator so that the special element acts as an identity for
the binary operator, and where the binary operator is associative. We
expect type signatures something like one :: m and mult :: m -> m -> m
so that, for example, m (m a b) c == m a (m b c).
>>

I don't get it right away, though, and the rest is code that I skip
because I just want info on monoids.

Another page : MonadPlus VS Monoids... Still not the basic info that
I'd love to find.

I am now at the end of the first page of google results, and I don't
have any clue about:

- what are the laws of a monoid besides it has an associative
operation and an identity ?
- what is the point of a monoid other than being a
generalisation/abstraction ? What kind of uses this particular
generalisation brings me ?

Part of the problem is that something like a monoid is so general that
I can't wrap my head around why going so far in the abstraction.
For example, the writer monad works with a monoid; using the writer
monad with strings makes sense because the mappend operation for lists
is (++), now why should I care that I can use the writer monad with
numbers
which it will sum ? ( if I understood correctly ! )

I don't care about the name, it's ok for me that the name
mathematicians defined is used, but there are about two categories of
people using haskell and
I would love that each concept would be adequately documented for everyone:
- real-world oriented programming documentation with usefulness and
examples for the non mathematician
- the mathematics concepts and research papers for the mathematicians
for those who want/need to go further

As someone mentionned, the documentation can't really be done by
someone that doesn't fully grok the concepts involved.