[Haskell-cafe] who's in charge?

[Gaius Hammond]

On 29 Oct 2010, at 07:33, 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?



Yes I had a bit of a rant about that in my blog recently http://gaiustech.wordpress.com/2010/09/27/api-documentation/



It's by no means only Java; automated documentation generators are the  
problem. They add no more value than a smart editor could give you  
anyway, or reading the comments. You need an API reference *and*  
sample code *and* a high level introduction and explanation of intent  
to count as "documentation" in my book.



Cheers,



G