A documentation generator is a programming tool that generates documentation intended for programmers or end users , or both, from a set of specially commented source code files, and in some cases, binary files....
Sun Microsystems, Inc. was a company that sold :computers, computer components, :computer software, and :information technology services. Sun was founded on February 24, 1982...
An application programming interface is a source code based specification intended to be used as an interface by software components to communicate with each other...
Java is a programming language originally developed by James Gosling at Sun Microsystems and released in 1995 as a core component of Sun Microsystems' Java platform. The language derives much of its syntax from C and C++ but has a simpler object model and fewer low-level facilities...
source code.
The "doc comments" format used by Javadoc is the de facto industry standard for documenting Java classes. Some IDE
Integrated development environment
An integrated development environment is a software application that provides comprehensive facilities to computer programmers for software development...
NetBeans refers to both a platform framework for Java desktop applications, and an integrated development environment for developing with Java, JavaScript, PHP, Python, Groovy, C, C++, Scala, Clojure, and others...
Eclipse is a multi-language software development environment comprising an integrated development environment and an extensible plug-in system...
automatically generate Javadoc HTML. Many file editors assist the user in producing Javadoc source and use the Javadoc info as internal references for the programmer.
Doclet programs work with the Javadoc tool to generate documentation from code written in Java.Doclets are written in the Java programming language and use the doclet API to:* Select which content to include in the documentation....
and taglets, which allows you to analyze the structure of a Java application. This is how JDiff
JDiff
JDiff is a Javadoc doclets which generates an HTML report of all the packages, classes, constructors, methods, and fields which have been removed, added or changed in any way, including their documentation, when two Java APIs are compared. This is very useful for describing exactly what has changed...
can generate reports of what changed between two versions of an API.
Structure of a Javadoc comment
A Javadoc comment is set off from code by standard multi-line comment tags /* and */. The opening tag, however, has an extra asterisk, as in /**.
The first paragraph is a description of the method documented.
Following the description are a varying number of descriptive tags, signifying:
The parameters of the method (@param)
What the method returns (@return)
Any exceptions the method may throw (@throws)
Other less-common tags such as @see (a "see also" tag)
Overview of Javadoc
The basic structure of writing document comments is embed them inside /** ... */. The Javadoc is written next to the items without any separating newline. The class declaration usually contains:
/**
* @author Firstname Lastname
* @version 1.6 (the version of the package this class was first added to)
* @since 2010-03-31 (a date or the version number of this program)
*/
public class Test {
// class body
}
For methods there is (1) a short, concise, one
line description to explain what the item does. This is followed by [2] a longer description that may span in multiple
paragraphs. In those the details can be explained in full. This section, marked in brackets [], is optional. Last, there is (3) a tag section to list
the accepted input arguments and return values of the method.
/**
* Short one line description. (1)
*
* Longer description. If there were any, it would be [2]
* here.
*
* @param variable Description text text text. (3)
* @return Description text text text.
*/
Variables are documented similarly to methods with the exception that part (3) is omitted. Here the variable
contains only the short description:
/**
* Description of the variable here.
*/
private int debug = 0;
Some of the available Javadoc tags are listed in the table below:
Tag & Parameter
Usage
Applies to
Since
@authorname
Describes an author.
Class, Interface, Enum
@versionversion
Provides software version entry. Max one per Class or Interface.
Class, Interface, Enum
@sincesince-text
Describes when this functionality has first existed.
Class, Interface, Enum, Field, Method
@seereference
Provides a link to other element of documentation.
Describes an exception that may be thrown from this method.
Method
@deprecateddescription
Describes an outdated method.
Method
{@inheritDoc}
Copies the description from the overridden method.
Overriding Method
1.4.0
{@linkreference}
Link to other symbol.
Class, Interface, Enum, Field, Method
{@value}
Return the value of a static field.
Static Field
1.4.0
Example
An example of using Javadoc to document a method follows. Notice that spacing and number of characters in this example are as conventions state.
/**
* Validates a chess move.
*
* Use {@link #doMove(int, int, int, int)} to move a piece.
*
* @param theFromFile file from which a piece is being moved
* @param theFromRank rank from which a piece is being moved
* @param theToFile file to which a piece is being moved
* @param theToRank rank to which a piece is being moved
* @return true if the move is valid, otherwise false
*/
boolean isValidMove(int theFromFile, int theFromRank, int theToFile, int theToRank)
{
...
}
/**
* Moves a chess piece.
*
* @see java.math.RoundingMode
*/
boolean doMove(int theFromFile, int theFromRank, int theToFile, int theToRank)
{
...
}
