Quoting Martin Kersten <[EMAIL PROTECTED]>: > After going through it again, the JavaDoc API documents are > available online statement, mention to read the package description. Maybe > this should be said top level. The documentation is hidden within the API > documentation. You know I just glaced over it and saw the api > documentation is online. The second line didn't seam to be important at > first... >
In the home page for Digester: http://jakarta.apache.org/commons/digester/ the second section of the overview is entitled "Documentation". And the second paragraph there states: The JavaDoc API Documents are available online. In particular, you should read the package description for the org.apache.commons.digester package for detailed information on using the package. I'm not sure how we can say it any more "top level" than that, but would certainly be interested in any ideas there. (A similar comment is made on the first page of the JavaDocs themselves.) On the general topic of including user guide documentation in the JavaDocs, you'll find this to be quite common in the various Commons packages. The reasoning is that these packages are, after all, class libraries to be used by developers, and those developers are going to need the JavaDocs in order to understand the valid method signatures and so on, no matter what. Too often, I've seen cases where class libraries were documented separately, and the user guide was never read because developers tended to think a "user guide" is for the user of their own application, not for the library they are trying to use, and wouldn't read it. This way, all the information that a developer needs is accessible in one place. A separate benefit is that the user guide can contain direct links to the detailed JavaDocs for the classes it talks about, because the directory structure for where package.html files go is well defined. Trying to do this with separated user guides leads to much more fragile links, in my experience. Thanks for your offer to help! Craig McClanahan --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
