On Dec 19, 2011, at 1:01 PM, Richard O'Keefe wrote:
>
> 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?"
I agree, though really much of that kind of information should be in the Monoid
typeclass rather than in the Maybe instance in particular.
> 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.
I understand what you are getting at here, but the reason why think that the
word "warning" needs to appear somewhere is to get users' attention long enough
to let them know that this instance might break their expectations since it is
inconsistent with MonadPlus and Alternative.
Nonetheless, I agree that it is a good idea to let users know that the
alternative behavior might be the most useful one in their own case, so how
about the following (including changes listed in an earlier e-mail), which I
will call Version 5:
================================================================
This instance satisfies the property that, for all x any y:
(1) Nothing `mappend` Nothing = Nothing
(2) Just x `mappend` Nothing = Just x
(3) Nothing `mappend` Just y = Just y
(4) Just x `mappend` Just y = Just (x `mappend` y)
Put in formal terms, this instance performs the standard procedure of
turning an arbitrary semigroup into a monoid by simply adding a new element to
the semigroup to serve as the identity element, where in this case the identity
element is the Nothing value of Maybe; unfortunately, since the base libraries
do not come with a Semigroup typeclass, this process is expressed in code as
lifting from the Monoid typeclass.
CAVEAT: Note that rule (4) here is different from the case of the
MonadPlus/Alternative instances where the Just y value is discarded so that
Just x `mplus` Just y = Just x <|> Just y = Just x; if this is alternative
behavior is what you were looking for, then try those typeclasses instead.
================================================================
Cheers,
Greg_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
