JavaDoc 1

JavaDoc
JavaDoc 2
Outline

What is JavaDoc?
JavaDoc Comments
JavaDoc Tags
Generating JavaDoc Documentation
References

JavaDoc 3
What is JavaDoc?
A software tool developed by Sun Microsystems for
generating API documentation format from Java source
code augmented with special tags in the codes
comments.
An industry standard for documenting Java classes.
How does JavaDoc work?
Instead of writing and maintaining separate
documentation, the programmer writes formatted
comments in the Java code itself.
Javadoc takes these comments and transforms them
into documentation.
JavaDoc 4
What is JavaDoc?
Many such systems exist that can be used for various
programming languages:
Javadoc, Doxygen,
Many of these can output in different formats:
HTML, RTF, PDF, LaTeX, manpages,
HTML has many advantages:
Portable, browsable, adaptable
Doxygen is probably the most flexible of them all, as it
can generate documentation for various programming
languages and generate output in various formats.


JavaDoc 5
What is JavaDoc?
Advantages:
Program documentation process is coupled with the
programming process
Automated generation of documentation: less error-prone
Ease of generation of documentation
Ease of update of documentation
Short code-to-documentation cycle: all programmers can be
made aware of others developments almost in real time
Can generate highly browsable documentation, accessible
electronically over the web (HTML)


JavaDoc 6
What is JavaDoc?
Disadvantages:
There is a learning curve to learn how to use the tool,
though it is minimal
Requires dedication, or else the documentation will be
obsolete or incomplete.

JavaDoc 7
What is JavaDoc?
Example:
JavaDoc 8
JavaDoc Comments
A JavaDoc comment begins with the /** marker and ends with the
*/ marker. All the lines in the middle start with an asterisk lined up
under the first asterisk in the first line.
/**
* This is a <b>javadoc</b> comment.
*/
Because JavaDoc generates HTML files, any valid HTML can be
embedded. A JavaDoc comment may be composed of multiple
lines, for example:
/**
* This is line one.
* This is line two.
*
* This is intended as a new paragraph.
*/
JavaDoc 9
JavaDoc Comments
A JavaDoc comment is written in HTML and must precede a
class, field, constructor or method declaration.
The * character is a marker used to make the JavaDoc comments
more readable in the source file. They will not appear in the
generated HTML documents. Since the blanks and tabs are also
removed, we need to use an HTML tag <p> to mark a new
paragraph as in:
/**
* This is paragraph one.
*
* <p>
* This is paragraph two.
*
* <p>
* This is the last paragraph.
*/
JavaDoc 10
JavaDoc Comments
Another useful HTML marker is <code>, which we can use to
include a sample code in a JavaDoc comment. Any text between
the <code> and </code> markers will appear in a Courier font.
Example:
JavaDoc 11
JavaDoc Comments
The generated HTML will be:
JavaDoc 12
JavaDoc Comments
For the JavaDoc comments to be recognized as such by the
javadoc tool, they must appear immediately before the class,
interface, constructor, method, or data member declarations.
If you put the JavaDoc comment for the class before the import
statements, it will be ignored.
The first sentence is a summary sentence. This should be a
short description of the element described by the comment.

Note:
JavaDoc does not provide a format for commenting elements
within methods, i.e. the local variables and the computing going
on inside the methods. But you still can use the regular comments
marks // or /*..*/, to comment this part of your program.
JavaDoc 13
JavaDoc Tags
Special tags can be embedded within the JavaDoc comments.
These tags start with the at symbol @.
JavaDoc tags must start at the beginning of a line.

Example:
JavaDoc 14
JavaDoc Tags
@author
Use this tag to create an author entry. You can have multiple
@author tags. This tag is meaningful only for the class/interface
JavaDoc comment.

@version
Use this tag to create a version entry. A JavaDoc comment may
contain at most one @version tag. Version normally refers to the
version of the software (such as the JDK) that contains this
feature.

@see
Use this tag to add a hyperlinked "See Also" entry to the class.
JavaDoc 15
JavaDoc Tags
Example:
JavaDoc 16
JavaDoc Tags
Generated HTML:
JavaDoc 17
JavaDoc Tags
@param
Use this tag to add a parameter description for a method. This tag
contains two parts: the first is the name of the parameter and the
second is the description. The description can be more than one line.

@param size the length of the passed array

@return
Use this tag to add a return type description for a method. This
tag is meaningful only if the methods return is non-void.

@return true if the array is empty; otherwise return false
JavaDoc 18
JavaDoc Tags
Example:
JavaDoc 19
JavaDoc Tags
Generated HTML:
JavaDoc 20
Generating JavaDoc Documentation
After adding the JavaDoc comments to the source files, we use the
javadoc command to generate the documentation.
We run the javadoc as we run javac or java tools.
After the javadoc command, we provide the parameters, when the
mandatory ones are either the packages name or the source file
name.

Example:
In order to enforce JavaDoc to generate documentation for the complete
GIPSY package, we write:
javadoc gipsy

In order to enforce JavaDoc to generate documentation for the
JINITransportAgent.java file, to include the author and version tag and to
include all the classes, attributes and methods we write:
javadoc -private -version -author JINITransportAgent.java
JavaDoc 21
Generating JavaDoc Documentation
Example:

The source java file with built in JavaDoc documentation:
JINITransportAgent.java

The generated HTML documentation:
JINITransportAgent.html
JavaDoc 22
Sun Microsystems, How to Write Doc Comments for the Javadoc Tool,
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html

Emil Vassev, DMS API Documentation, Concordia University, Montreal,
Quebec, Canada, 2005

Wikipedia. Comparison of Documentation Generators.
http://en.wikipedia.org/wiki/Comparison_of_documentation_generators

References