Safe Javadoc Editor
Original Publication Date: 2003-Nov-24
Included in the Prior Art Database: 2003-Nov-24
Javadoc is a technology used to generate documentation of Java programming APIs directly from specially formatted comments in the source files. This article describes an application that supports the development of Javadoc source by an information development team that is separate from the program developers while still protecting program code from inadvertent changes.
Safe Javadoc Editor
Java source code is frequently documented using Javadoc, a set of standard textual elements that can be included in source code comments. These tagged elements are then processed by various transforms that are often used as inputs to customer documentation (particularly in API references and other documents intended for an audience of programmers). For a small team where the programmers are responsible for the code as well as the documentation, this is not problematic.
The problem arises in a team environment where code development and documentation are the responsibilities of separate groups. Because the Java source files are owned by the programming team, and because of the danger of inadvertent changes to program code, it is often impractical for the documentation team to directly modify the comments in the Java source. However, information authored by the programming team should not be delivered to customers without the involvement of the documentation team; otherwise, problems may result in readability, consistency, terminology, and globalization.
This problem would be solved by a Javadoc editor specifically meant for use by a documentation team in a collaborative environment where the program source code and the documentation are owned by different teams. Such an editor would include sufficient intelligence to parse a Java source file in order to clearly identify which parts are safe to modify by a user who has a documentation role (this...