- Properly document Java source code according to established standards
- Use the javadoc documentation tool to create HTML documentation from source code
- Java has published documentation standards
- The javadoc tool is used to create web pages of documentation from comments embedded in the source code
- The javadoc tool looks for special block comments that start with /**
- The text inside the comment is used for documentation and is free form text which can be styled with basic HTML tags
- Specially marked tags within the comments specify specific, important information
- Since the generated documentation will be web pages, the HTML tags in the comments are turned into the appropriate styles in the web pages
- javadoc even allows intra-linking among parts of the documentation, linking to external sites, and automaticaly linking to the appropriate official Java documentation
- You can also include images in the documentation (place linked files in a subdirectory named doc-files)
- The documentation comments must appear just before the feature they document
- The first sentence in the comment should be a brief summary
- Tags start with an @ symbol
- @author name: used for the class only
- @version text: used for the class only
- @since text
- @deprecated text
- @see reference: where reference is one of
- <a href="url">label</a>
- package.class#feature label
- "text"
- @param var desc: used with methods
- @return desc: used with methods
- @throws class desc: used with methods
- {@link package.class#feature label}: links to other documentation pages
- To compile documentation: javadoc -d docDirectory packageList
- There are many options available such as linking to the source files
- You can add package documentation comments in two ways
- Add a package.html file with the documentation comments between <body> and </body> tags
- Supply a package-info.java file that start with the javadoc format comments you want to include and then has the package statement
- You can add an overview by adding an overview.html page