2014-10-01 17:28 GMT+04:00 Mark Thomas <ma...@apache.org>: > 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
The "className" attribute is just a details on how Digester works for this specific format of configuration files. It is not needed if you configure embedded Tomcat. There is no need for it to appear in 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 You wanna take a bite at documenting Connector / Protocol / Endpoint attributes and their aliases? > 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? I do not like the idea. 1. Many Tomcat administrators are not programmers. They will not be happy digging into Tomcat internals. (I have read such concerns many times with regards to Tomcat logging configuration). 2. Javadoc is many megabytes and many small documents. It takes much disk space. It is also unrealistic to expect one to review and read most of them. (E.g., when I install Apache Ant by unzipping their bin.zip file, I usually delete their Javadoc. An installed version of Ant. with manuals included but without "manual/api" directory, is just 6Mb. (On example of version 1.9.3) The Javadocs part of the manual is 32 Mb.) 3. I think that Javadoc is mostly for our self-reference. It is not the best place to document configuration options. It may be of some use to people using embedded Tomcat. 4. Javadoc is not integrated with Apache Comments system. 5. It takes more than a minute to run "ant javadoc" for Tomcat 8. It takes seconds to rebuild documentation webapp. 6. Most of classes are considered our internal API, with any changes being allowed between releases. If we refactor the code (e.g. move the classes or extract a super class), documentation links to javadoc might break. 7. Technically, if we install Javadoc in addition to the main documentation web application, my proposal would be to install it as an unpacked war, "docs#api.war" with unpackWAR=false in its META-INF/context.xml file. A drawback is that Tomcat will refuse to starts that web application if SecurityManager is enabled (as it refuses to start applications that have a context.xml file). Best regards, Konstantin Kolinko --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org For additional commands, e-mail: dev-h...@tomcat.apache.org
