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