[Haskell-cafe] who's in charge?

[Richard O'Keefe]

On 29/10/2010, at 7:33 PM, Gregory Crosswhite wrote:

> Also, this is a complete aside but what the heck.  :-)
> 
> Has anyone else been driven crazy by the way that Java code and libraries are documented?  It seems like whenever I try to figure out how to use a piece of Java code, the functionality is spread out over a huge collection of classes and methods so that it is impossible to figure out where things actually happen and how the code is supposed to be used.  Am I correct to perceive this as a general trend in Java, or is it just the projects that I looked at and/or my lack of experience in how Java sources and libraries are organize?

Talking about documentation in the 3rd year software engineering paper I teach,
I give JavaDoc as an example of what not to do.  I give R as an example of
something that works quite well.  It's *examples* that make the difference.

One thing I will say for the JavaMail specification is that it has some useful
examples.