Darren New wrote:
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.
For the example given above (something truly new), then I would use
Javadoc to add a link to a more in depth description or manual detailing
the new thing. This way the details are removed from the code (saving
one from having a manual embedded in the source), but still available if
the reader wants more information. In fact, much of the Javadoc I
reference from Sun has this sort of documentation. There are many
instances where a link to a tutorial and/or example code can be found.
Often the reason that good comments and/or documentation doesn't happen
is because programmers want to code, not document. Also, many of them
are rotten technical writers.
The number of programmers who can also write is vanishingly small.
And even smaller is the number of programmers who *want* to write.
I see we agree on this. :)
In my experience, most projects provide suckalicious documentation.
There are a few well-documented libraries out there. Not enough, tho.
And this.
PGA
--
Paul G. Allen, BSIT/SE
Owner, Sr. Engineer
Random Logic Consulting Services
www.randomlogic.com
--
[email protected]
http://www.kernel-panic.org/cgi-bin/mailman/listinfo/kplug-lpsg
