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

[Richard O'Keefe]

On 19/12/2011, at 3:44 PM, Gregory Crosswhite wrote:
> So what do you all think about my own suggestion for the documentation?

It is an improvement.

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?"

One important thing about the Monoid instance for Maybe is that

	There is more than one way to turn Maybe into a Monoid.
	One way treats Maybe a as a truncated [a] and does not
	depend on any properties of a, it takes
	mappend (Just x) _ = Just x

	The other requires a itself to be a Monoid, and lift's
	a's operations to Maybe a:
	mappend (Just x) (Just y) = mappend x y
	The latter, more interesting, case is the one implemented here.

(In the same way, bounded integers like Int can be viewed as Monoids in
at least 4 ways, only two of which are predefined in Data.Monoid.
   mempty = minBound
   mappend = max

   mempty = maxBound
   mappend = min
are the other two.  In fact these apply to anything that is Bounded and Ord.)

The point is not that your proposed documentation doesn't say that, but it
doesn't say that the MonadPlus reading is a *LEGITIMATE* way to view Maybe
as a Monoid, which happens not to have been the one chosen; also that this
possibility that the Monoid instance you WANT might not be the one you GET
is to me the first thing you need to understand about it.  Yes, there is a
blanket warning about this, but it specifically mentions Num.  Whenever it
is possible for a reasonable person to want a Monoid instance and get one
that is not the instance s/he wanted, it's worth highlighting in the docs.