[Haskell-cafe] Comments from OCaml Hacker Brian Hurt

[Ross Mellgren]

Of course not, the wikipedians would probably have your head for  
notability guidelines or something ;-)

But seriously, I would have saved many hours of my life and probably  
many future ones if type class instances were documented and showed up  
in the haddock docs.

-Ross

On Jan 15, 2009, at 11:53 AM, Lennart Augustsson wrote:

> By no means do I suggest that Wikipedia should replace Haskell library
> documentation.
> I think the libraries should be documented in a mostly stand-alone way
> (i.e., no references to old papers etc.).  In the case of Monoid, a
> few lines of text is enough to convey the meaning of it and gives an
> example.
>
>  -- Lennart
>
> On Thu, Jan 15, 2009 at 4:46 PM, Ross Mellgren <rmm- 
> haskell at z.odi.ac> wrote:
>> For what it's worth, many (most/all?) programmers I know in person  
>> don't
>> have the slightest clue about Category Theory and they may have  
>> known about
>> abstract algebra once upon a time but certainly don't remember any  
>> of it
>> now. They usually understand the concepts perfectly well enough but  
>> by "lay
>> terms" or by no particular name at all.
>>
>> Personally, I don't mind it too much if the generic typeclasses are  
>> named
>> using extremely accurate terms like Monoid, but saying that someone  
>> should
>> then look up the abstract math concept and try to map this to  
>> something very
>> concrete and simple such as a string seems like wasted effort.
>>
>> Usually when encountering something like "Monoid" (if I didn't  
>> already know
>> it), I'd look it up in the library docs. The problem I've had with  
>> this
>> tactic is twofold:
>>
>> First, the docs for the typeclass usually don't give any practical  
>> examples,
>> so sometimes it's hard to be sure that the "append" in "mappend"  
>> means what
>> you think it means.
>>
>> Second is that there appears to be no way to document an  
>> _instance_. It
>> would be really handy if there were even a single line under  
>> "Instances >
>> Monoid ([] a)" that explained how the type class was implemented  
>> for the
>> list type. As it is, if you know what a Monoid is already, it's  
>> easy to
>> figure out how it would be implemented. If you don't, you're either  
>> stuck
>> reading a bunch of pages on the generic math term monoid and then  
>> finally
>> realizing that it means "appendable" (and other similar things), or
>> grovelling through the library source code seeing how the instance is
>> implemented.
>>
>> My 2 cents,
>>
>> -Ross
>>
>>
>> On Jan 15, 2009, at 11:36 AM, Lennart Augustsson wrote:
>>
>>> Most people don't understand pure functional programming either.   
>>> Does
>>> that mean we should introduce unrestricted side effects in Haskell?
>>>
>>> -- Lennart
>>>
>>> On Thu, Jan 15, 2009 at 4:22 PM, Thomas DuBuisson
>>> <thomas.dubuisson at gmail.com> wrote:
>>>>
>>>> On Thu, Jan 15, 2009 at 4:12 PM, Sittampalam, Ganesh
>>>> <ganesh.sittampalam at credit-suisse.com> wrote:
>>>>>
>>>>> Lennart Augustsson wrote:
>>>>>>
>>>>>> I have replied on his blog, but I'll repeat the gist of it here.
>>>>>> Why is there a fear of using existing terminology that is exact?
>>>>>> Why do people want to invent new words when there are already
>>>>>> existing ones with the exact meaning that you want? If I see  
>>>>>> Monoid I
>>>>>> know what it is, if I didn't know I could just look on Wikipedia.
>>>>>> If I see Appendable I can guess what it might be, but exactly  
>>>>>> what
>>>>>> does it mean?
>>>>>
>>>>> I would suggest that having to look things up slows people down
>>>>> and might distract them from learning other, perhaps more useful,
>>>>> things about the language.
>>>>
>>>> Exactly.  For example, the entry for monoid on Wikipedia starts:
>>>> "In abstract algebra, a branch of mathematics, a monoid is an
>>>> algebraic structure with a single, associative binary operation  
>>>> and an
>>>> identity element."
>>>>
>>>> I've had some set theory, but most programmers I know have not.
>>>>
>>> _______________________________________________
>>> Haskell-Cafe mailing list
>>> Haskell-Cafe at haskell.org
>>> http://www.haskell.org/mailman/listinfo/haskell-cafe
>>
>> _______________________________________________
>> Haskell-Cafe mailing list
>> Haskell-Cafe at haskell.org
>> http://www.haskell.org/mailman/listinfo/haskell-cafe
>>