SJS wrote:
Packages nest quite nicely, which is an appropriate level for that
sort of documentation.
Well, I was thinking about this more...
If you don't know how public key cryptography works, reading the OpenSSL
man pages isn't going to help you much. If you don't know how 3D
graphics works, reading the OpenGL man pages isn't going to help much.
And so on.
If you invent something truly new, you need something more than the
level of man pages to explain what's going on before its usable.
Javadocs is good for some kinds of documentation. It's not good for all
kinds of documentation. It can be a good reference material if well
written.
My experience is that every project with nothing but auto-generated
documentation has essentially unusable documentation. Even if it's
possible to build module-level documentation, it doesn't happen.
Of course, that's not the fault of the tool.
Try to learn (say) J2EE by reading module-level documentation.
Using J2EE to criticize Java is like using C++ to criticize C.
Who is criticizing java? I'm just saying that without an overview, a
reference to individual routines isn't going to teach you how to use the
library. No more than handing you the STL documentation is going to
teach you how to program in C++.
How early are you thinking of? Java's documentation has been reasonable
for as long as I have been using it... it's the more RECENT stuff that's
getting useless.
The very first versions had the same documentation, word for word, for
read/write, and for a couple of the data structures (hashtable and
vector or something?) Clearly the programmer writing the documentation
didn't even take the time to even type the documentation for each
routine separately.
The number of programmers who can also write is vanishingly small.
And even smaller is the number of programmers who *want* to write.
In my experience, most projects provide suckalicious documentation.
There are a few well-documented libraries out there. Not enough, tho.
--
Darren New / San Diego, CA, USA (PST)
"That's pretty. Where's that?"
"It's the Age of Channelwood."
"We should go there on vacation some time."
--
[email protected]
http://www.kernel-panic.org/cgi-bin/mailman/listinfo/kplug-lpsg
