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. _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe