On Documenting with JavaDoc
Documentation is the bridge between the general specifications for your program and the actual code. You should document your code either before or while you write it, not as an afterthought.
Using JavaDoc comments (/** */) you should include at least:
- A description of each class, including author and version/date.
- A description of each method, including acceptable arguments, return values, global variables affected, exceptions thrown, and what the method does.
- A description of any public variables.
You should also use implementation comments (/* */ and //) to comment on tricky or confusing sections of code.
JavaDoc
When you're done writing your code, you can type:
javadoc [file].java
at the command line, where [file].java is your source code.
This will create a webpage of your documentation that looks like the Java API Documentation.
The javadoc tool takes a number of command line arguments. Some of the more useful ones are:
- -private -- document all classes and methods
- -package -- document all classes and methods except private ones.
- -d <directory> -- puts docs in a certain directory (needs to exist first)
- -author -- includes @author tags
- -version -- includes @version tags
- -window-title -- adds a title for your documentation
- -link <url> -- will update links to point to documentation of standard classes at <url>. (You must be connected for this to work, as it checks the package-list at the URL).
- -help -- learn more of these arguments
So, an example javadoc command is:
javadoc -author -version -package -d docs -windowtitle "Assignment 1 Documentation" -link http://java.sun.com/j2se/1.3/docs/api/ *.java
You can learn more about JavaDoc in general and How to Write JavaDoc Comments directly from java.sun.com.