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.