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

[Richard O'Keefe]

On 17/12/2011, at 3:35 PM, Matthew Farkas-Dyck wrote:

> On 15/12/2011, Gregory Crosswhite <gcrosswhite at gmail.com> wrote:
>> 1) Documentation really needs to be improved
>> 2) some/many cannot be physically separated from Alternative, but there
>> *might* be an advantage to creating a subclass for them anyway purely for
>> the sake of conveying more information about a type to users
>> 3) Maybe and [] are sensible instances of Alternative, even if many/some
>> often enters an infinite loop.
>> 4) It is possible to provide special instance of many/some that satisfy the
>> equations of many/some, with the slight disadvantage that these solutions
>> are no longer the "least" solutions.
>> 
>> Based on all of this, at this moment in time it seems to me that the most
>> sensible way forward is to fix the documentation, tweak the definition of
>> Alternative to no longer require the least solutions of the equations, and
>> then to adopt the new instances for Maybe and [].
>> 
>> Thoughts?
> 
> (1) If we do (4), then the documentation ought to be adequate as-is.

No.  Not by a country mile.
It's better than "non-existent".
It's better than "misleading".
But it's not even on the same *continent* as "adequate".

A lot of Haskell packages have pretty much the same level of documentation.
And I didn't pay one single cent for it, so I can't scream too loudly.
But let's not kid ourselves.