Documentation

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 overviewby adding an overview.html page