SJS wrote:
This is why I like Java's Javadoc... method-level documentation, class-
level documentation, and module-level (or package-level) documentation,
all derived from the source tree.
First, it still generally doesn't help if stuff spans more than one
module. Try to learn (say) J2EE by reading module-level documentation.
Second, most of the stuff I've seen is documented like this:
void blarg(int arg)
Blargs the arg.
Indeed, the early Java stuff was documented like this:
void read(buf)
Reads the buffer
void write(buf)
Writes the buffer
because they didn't bother to change the copy/paste errors in the source.
At least when you're actually sitting there and writing documentation,
you can think about something *other* than the code.
Granted, it doesn't have to be bad. But in my experience, any library
that gives you *only* auto-extracted documentation has suckalicious
documentation. Anyone doing serious development for useful libraries
does the documentation first, and something winds up without a good
place to put it in the code.
--
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
