[Haskell-cafe] [Alternative] summary of my understanding so far

[Gregory Crosswhite]

On Dec 19, 2011, at 1:01 PM, Richard O'Keefe wrote:

> Documentation for a library module needs to start by telling people what
> it is for.  For a particular function, someone needs to know very quickly
> "is this what I am looking for? is this the kind of thing I _should_ have
> been looking for?"

As I said before, some of this information really belongs in the Monoid typeclass itself, so here is my attempt at adding more information in this vein to the Monoid typeclass:

================================================================

The Monoid typeclass provides a standard interface for specifying how pairs of values of a given type can be combined to form new values of that type, as well well as an identity value for that type that when combined with any value x produces x.  The Monoid class typically appears in higher-order functions that produce a list of values that need to be summarized into a single result, such as in Data.Foldable.foldMap function or the Writer monad.

Formally, an instance of Monoid provides a binary associative operator with an identity element;  to do this one must specify (at a minimum) the methods mempty and mappend such that they obey following properties:

(*) mempty is the identity:
	mempty `mappend` x = x `mappend` mempty = x
(*) mappend is associative:
	x `mappend` (y `mappend` z) = (x `mappend` y) `mappend` z

Although not strictly necessary, for reasons of performance the Monoid typeclass also includes the method mconcat which combines all the elements in a list, i.e. it is a method which obeys the property

(*) mconcat = foldr mappend mempty

The above is the default definition of mconcat if no other is supplied, but for some times users may wish to override it when it can be performed more efficiently.  Regardless, the minimal complete definition for an instance of the Monoid typeclass is mempty and mappend.

For many types there are multiple equally sensible ways to combine pairs of values;  for example, for the Int type one could use either addition or multiplication.  In such cases where there is no single "natural" way to combine values, we often (though not always) define newtype wrappers for these types so that we can make it explicit which operation we are using.  In the case of the Int type, for example, we define the Sum and Product newtypes and make these instances of Monoid using the corresponding mathematical operator.

================================================================

This additional information unfortunately makes the documentation more verbose, but the hope was to try to explain as much as possible the "whys" and "whens" of the Monoid class (to a non-mathematician audience) in addition to the "whats", since as you point out often the most important part of the documentation is where it explains why something exists and when you would need it.

Cheers,
Greg
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/haskell-cafe/attachments/20111219/4ff6b62f/attachment.htm>