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_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
