5 ms·
It's interesting that everyone commenting so far has picked up on the auto-documentation issue. The main value of these tools, IMHO, is in their ability to pre
by Silhouette 17y ago
It's interesting that everyone commenting so far has picked up on the auto-documentation issue.
The main value of these tools, IMHO, is in their ability to present a high-level overview of the code and support drilling down to find the relevant parts for the task at hand, not as a substitute for just reading comments in the code once you've found it. In fact, one of the worst aspects of many auto-documentation tools is the way they obfuscate comments that would otherwise have been written in plain text. Seriously, Javadoc, why do I have to write a <p> between each paragraph just so you can lay the comments out properly in HTML?
To improve the scannability of auto-generated documentation, top of my wish list would be an "important" flag you could put on the key types, functions, etc. Existing tools typically have no sense of priority in the way that a human writer would, giving equal weight to the top-level function that implements an important algorithm and each of a dozen trivial utility functions. Then you wind up with dozens of mostly irrelevant details obscuring the few key points of interest.
The other thing I really wish they'd support is much better grouping of related information. If a bunch of functions and types would naturally be of interest at the same time, then they should be listed together or otherwise associated in the documentation. Most auto-documentation tools suck at this, and even those that provide some facilities to do it tend to fall into the obfuscation trap I mentioned earlier.
- timf 17y ago> an "important" flag you could put on the key types, functions, etc. I liked the "start here" pictures here: http://www.gridgain.com/javadoc/index.html http://www.gridgain.com/javadoc/index.html > grouping of related information I agree -- if the output of this could be made to make sense. I usually end up doing this manually in a tutorial with a bunch of English around it, I'm skeptical that a list of related items, even if carefully picked, would do much good without that hand-held context from "above" the situation.