I've had improving the documentation at the back of my mind for some time. One of the things that bugs me is the duplication - particularly between the configuration documentation and the Javadoc. With this in mind I have been mulling over the follow idea. Feedback welcome.
Remove the bulk of the configuration section of the JavaDoc, replacing it with a graphical overview of Tomcat's internal structure linked to the relevant JavaDoc for each component. The general description of a component would move to the interface Javadoc as would the information on the common attributes. Implementation specific information would move to the implementation Javadoc. There are some special cases. The ones that come immediately to mind are: - className attribute. Never appears in Javadoc. Document it and other information about standard implementations etc. in the appropriate class level Javadoc - attributes set by reflection and setProperty. Document them, with links to the Javadoc for where they are really set in the appropriate class level Javadoc I am sure there are others. I am confident suitable approaches can be found for each. I'd also like to review the various How To documents and move as much as possible to Javadoc - probably as package level documentation. A major issue is that we don't install Javadoc buy default. My proposal for this is to leave the links as local links but write a Servlet (or maybe a JSP) to handle all requests for local Javadoc as follows: - if local Javadoc is installed, use it - if local Javadoc is not installed and the user has not previously given permission to redirect to the Tomcat website request permission to redirect the request to the Javadoc hosted on the Tomcat web site - if local Javadoc is not installed and the user has previously expressed a preference regarding redirection in that session, abide by that preference Thoughts? Mark --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org For additional commands, e-mail: dev-h...@tomcat.apache.org
