[Haskell-cafe] Comments from OCaml Hacker Brian Hurt

[Jonathan Cast]

On Thu, 2009-01-15 at 21:17 +0000, Andrew Coppin wrote:
> Sebastian Sylvan wrote:
> >
> >
> > On Thu, Jan 15, 2009 at 7:46 PM, Andrew Coppin 
> > <andrewcoppin at btinternet.com <mailto:andrewcoppin at btinternet.com>> wrote:
> >
> >     The sad thing is, it's not actually complicated. The documentation
> >     just makes it seem like it is! :-(
> >
> >
> > This is so true for a heck of a lot of things. Existential 
> > quantification being just one of them. Loads of things in Haskell have 
> > big powerful (but scary) names which I really think intimidate people, 
> > the situation isn't helped when a lot of tutorials use the theoretical 
> > basis for the construct as a starting point, rather then actually 
> > describing the construct from the perspective of a programmer first 
> > (see Monads).
> > Haskell really isn't that difficult compared to other languages, but 
> > people still get the impression that you need to be a big brain on a 
> > stick to use it, terminology is certainly part of the equation.
> >
> > This doesn't mean that making up new words is always better, but we 
> > should certainly strive to exploit any opportunity to clarify the 
> > issue and (this means that haddock comments and language 
> > books/tutorials shouldn't refer to academic papers first and foremost, 
> > but use common English and practical examples to describe what's being 
> > used, and academic nerds can consult the footnotes for their fill of 
> > papers containing pages of squiggly symbols!).
> 
> I basically agree with most of what you just said.
> 
> I'm not sure having a Monoid class is actually useful for anything - but 
> if we must have it, there seems to be little better possible name for 
> something so vague.
> 
> {-# LANGUAGE ExistentialQuantification #-} is an absurd name and should 
> be changed to something that, at a minimum, tells you it's something to 
> do with the type system. (Ideally it would also be pronouncible.) Of 
> course, nobody will take any notice, since changing this would induce 
> mass breakage for all the millions of LoC that already use the old name.
> 
> I think "documenting" a package by saying "read this academic paper" 
> should be banned. (Most especially if the paper in question isn't even 
> available online and can only be obtained from a reputable university 
> library!!) For example, I was looking at one of the monad transformers 
> (I don't even remember which one now), and the Haddoc contained some 
> type signatures and a line saying "read this paper". The paper in 
> question mentioned the transformer in passing as a 5-line example of how 
> to use polymorphism, but *still* without explaining how to actually use 
> it! (I.e., the paper was about polymorphism, and this transformer was 
> just a quick example.) What the hell??
> 
> I presume I can call "more documentation please!" without upsetting even 
> the most ardant category theory millitant... ;-)

But you don't seem to be capable of separating your valid complaints
from your invalid ones.  Everyone wants the Haddock documentation to be
maximally useful.  But the should never be a confusion between
*defining* a term used in a library and *choosing* that term.  They are
simply different activities, and neither can be a substitute for the
other.

jcc