Documenting Classes with JavaDoc
JavaDoc is a tool for generating API documentation in HTML format from comments placed in Java source code files. The JavaDoc tool is a standard part of the JDK installation. In this phrase, we show one sample usage of the JavaDoc tool. JavaDoc has many command-line options and flags that can be used to document classes and packages. For a full description of the options available when using JavaDoc, refer to the Sun documentation at: http://java.sun.com/j2se/1.5.0/docs/guide/javadoc/index.html. The javadoc command used in this phrase will generate JavaDoc documentation for all classes contained in the java.net package and all of its subpackages. The source code is assumed to be in the \home\src directory. The output of the command will be written to the \home\html directory. Inside a Java source file, a typical JavaDoc comment looks like this: /** * A comment describing a class or method * * Special tags preceded with the @ character to * document method parameters, return types, * Method or class author name, etc. Below is an * example of a parameter being documented. * @parameter input The input data for this method. */ The /** and */ character sequences denote the beginning and end of a JavaDoc comment. The output of the JavaDoc tool is the standard Java class documentation that you are most likely used to seeing if you've viewed any Java documentation online in the past. The JDK itself is thoroughly documented using JavaDoc documentation. You can view the JavaDoc for the JDK at: http://java.sun.com/j2se/1.5.0/docs/api/index.html JavaDoc generated documentation makes it easy to browse through the classes that make up an application or library. An index page is provided that indexes all the classes with hyperlinks to each class. Indexes are also provided for each package. It is common to integrate the creation of JavaDoc documentation with an application's build process. So, for example, if you are using the Ant build tool, there is an Ant task available for generating JavaDoc as part of your build. The technology that enables JavaDoc to work has also been used recently to create other tools to perform tasks that go beyond just documenting Java files. The Doclet API powers JavaDoc and these third-party tools. One of the most popular third-party uses of the Doclet API is the open source project XDoclet. XDoclet is an engine that enables attribute-oriented programming. With XDoclet, you can add metadata to your source code to automate tasks such as EJB creation. To find out more about XDoclet, you can find it online at: http://xdoclet.sourceforge.net/. Another API for working with JavaDoc style comments that is part of standard Java is the Taglet API. Using the Taglet API, you create programs called Taglets. Taglets can modify and format JavaDoc style comments contained in your source files. For more information about the Taglet API see: http://java.sun.com/j2se/1.4.2/docs/tooldocs/javadoc/taglet/overview.html |
