Javadoc Annotations

http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html

http://download.eclipse.org/modeling/mdt/xsd/javadoc/2.3.0/org/eclipse/xsd/class-use/XSDAnnotation.html

"The Javadoc^TM tool parses the declarations and documentation comments in a set of Java source files and produces a corresponding set of HTML pages describing (by default) the public and protected classes, nested classes (but not anonymous inner classes), interfaces, constructors, methods, and fields. You can use it to generate the API (Application Programming Interface) documentation or the implementation documentation for a set of source files."

The Javadoc tool processed files that end in .Java you can pass these in as individual files or as packages. You can also pass in wild cards i.e. *.java.

"Processing of links - During a run, the Javadoc tool automatically adds cross-reference links to package, class and member names that are being documented as part of that run. Links appear in several places:

Declarations (return types, argument types, field types)
"See Also" sections generated from @see tags
In-line text generated from {@link} tags
Exception names generated from @throws tags
"Specified by" links to members in interfaces and "Overrides" links to members in classes
Summary tables listing packages, classes and members
Package and class inheritance trees
The index

You can add hyperlinks to existing text for classes not included on the command line (but generated separately) by way of the -link and -linkoffline options."

Files do not have to include actual code to have a Javadoc page. Files could have the bare minimum Java file shell and annotations inside, so annotations could be included as part of the design process.

Javadoc annotations can be created while there are still bugs and errors in the code.

The Javadoc tool loads all referenced classes to create the documentation, so all of these classes must be available whether bootstrap classes, extensions, or user classes.

"You can customize the content and format of the Javadoc tool's output by using doclets. The Javadoc tool has a default "built-in" doclet, called the standard doclet, that generates HTML-formatted API documentation. You can modify or subclass the standard doclet, or write your own doclet to generate HTML, XML, MIF, RTF or whatever output format you'd like."

"Block tags and in-line tags - A tag is a special keyword within a doc comment that the Javadoc tool can process. There are two kinds of tags: block tags, which appear as @tag (also known as "standalone tags"), and in-line tags, which appear within curly braces, as {@tag}. To be interpreted, a block tag must appear at the beginning of a line, ignoring leading asterisks, white space, and separator (/**). This means you can use the @ character elsewhere in the text and it will not be interpreted as the start of a tag. If you want to start a line with the @ character and not have it be interpreted, use the HTML entity @. Each block tag has associated text, which includes any text following the tag up to, but not including, either the next tag, or the end of the doc comment. This associated text can span multiple lines."

So to make one of these "tags" we can say @tag or {@tag} but instead of the word tag you have what you want to call the actual tag, perhaps the methods name or something.

Comments should be written in HTML i.e. instead of > you have &gt.

"Leading asterisks - When javadoc parses a doc comment, leading asterisk (*) characters on each line are discarded; blanks and tabs preceding the initial asterisk (*) characters are also discarded. Starting with 1.4, if you omit the leading asterisk on a line, the leading white space is no longer removed. This enables you to paste code examples directly into a doc comment inside a <PRE> tag, and its indentation will be honoured. Spaces are generally interpreted by browsers more uniformly than tabs. Indentation is relative to the left margin (rather than the separator /** or <PRE> tag)."

So this means we can put comments into our javadoc like this:

/*@mycomment

*this is my code

* for(int i; i<10; i++)

* {

* println("Hello World!!");

* }

And our comment would appear in our java doc like this:

this is my code

for(int i; i<10; I++)

{

println("Hello World!!");

}

This means that when we have code as an actual comment it still has its proper indentations.

"First sentence - The first sentence of each doc comment should be a summary sentence, containing a concise but complete description of the declared entity. This sentence ends at the first period that is followed by a blank, tab, or line terminator, or at the first block tag. The Javadoc tool copies this first sentence to the member summary at the top of the HTML page."

"Declaration with multiple fields - Java allows declaring multiple fields in a single statement, but this statement can have only one documentation comment, which is copied for all fields. Therefore if you want individual documentation comments for each field, you must declare each field in a separate statement. For example, the following documentation comment doesn't make sense written as a single declaration and would be better handled as two declarations:

/**

* The horizontal and vertical distances of point (x,y)

public int x, y; // Avoid this

The Javadoc tool generates the following documentation from the above code:

public int x

The horizontal and vertical distances of point (x,y)

public int y

The horizontal and vertical distances of point (x,y)

Use header tags carefully - When writing documentation comments for members, it's best not to use HTML heading tags such as <H1> and <H2>, because the Javadoc tool creates an entire structured document and these structural tags might interfere with the formatting of the generated document. However, it is fine to use these headings in class and package comments to provide your own structure."

"The Javadoc tool has the ability to copy or "inherit" method comments in classes and interfaces under the following two circumstances. Constructors, fields and nested classes do not inherit doc comments.

Automatically inherit comment to fill in missing text - When a main description, or @return, @param or @throws tag is missing from a method comment, the Javadoc tool copies the corresponding main description or tag comment from the method it overrides or implements (if any), according to the algorithm below.

More specifically, when a @param tag for a particular parameter is missing, then the comment for that parameter is copied from the method further up the inheritance hierarchy. When a @throws tag for a particular exception is missing, the @throws tag is copied only if that exception is declared.

This behaviour contrasts with version 1.3 and earlier, where the presence of any main description or tag would prevent all comments from being inherited.

Explicitly inherit comment with {@inheritDoc} tag - Insert the inline tag {@inheritDoc} in a method main description or @return, @param or @throws tag comment -- the corresponding inherited main description or tag comment is copied into that spot. "

"JAVADOC TAGS

The Javadoc tool parses special tags when they are embedded within a Java doc comment. These doc tags enable you to autogenerate a complete, well-formatted API from your source code. The tags start with an "at" sign (@) and are case-sensitive -- they must be typed with the uppercase and lowercase letters as shown. A tag must start at the beginning of a line (after any leading spaces and an optional asterisk) or it is treated as normal text. By convention, tags with the same name are grouped together. For example, put all @see tags together.

Tags come in two types:

Block tags - Can be placed only in the tag section that follows the main description. Block tags are of the form: @tag.
Inline tags - Can be placed anywhere in the main description or in the comments for block tags. Inline tags are denoted by curly braces: {@tag}.

For information about tags we might introduce in future releases, see Proposed Tags.

The current tags are:

Tag	Introduced in JDK/SDK
`@author`	1.0
`{@code}`	1.5
`{@docRoot}`	1.3
`@deprecated`	1.0
`@exception`	1.0
`{@inheritDoc}`	1.4
`{@link}`	1.2
`{@linkplain}`	1.4
`{@literal}`	1.5
`@param`	1.0
`@return`	1.0
`@see`	1.0
`@serial`	1.2
`@serialData`	1.2
`@serialField`	1.2
`@since`	1.1
`@throws`	1.2
`{@value}`	1.4
`@version`	1.0"

"Where Tags Can Be Used

The following sections describe where the tags can be used. Note that these tags can be used in all doc comments: @see, @since, @deprecated, {@link}, {@linkplain}, and {@docroot}.

Overview Documentation Tags

Overview tags are tags that can appear in the documentation comment for the overview page (which resides in the source file typically named overview.html). Like in any other documentation comments, these tags must appear after the main description.

NOTE - The {@link} tag has a bug in overview documents in version 1.2 -- the text appears properly but has no link. The {@docRoot} tag does not currently work in overview documents.

Overview Tags

Package Documentation Tags

Package tags are tags that can appear in the documentation comment for a package (which resides in the source file named package.html or package-info.java). The @serial tag can only be used here with the include or exclude argument.

Package Tags

Class and Interface Documentation Tags

The following are tags that can appear in the documentation comment for a class or interface. The @serial tag can only be used here with the include or exclude argument.

Class/Interface Tags

An example of a class comment:

/**

 * A class representing a window on the screen.

 * For example:

 * <pre>

 *    Window win = new Window(parent);

 *    win.show();

 * </pre>

 * @author  Sami Shaio

 * @version %I%, %G%

 * @see     java.awt.BaseWindow

 * @see     java.awt.Button

*/

class Window extends BaseWindow {

...

Field Documentation Tags

The following are the tags that can appear in the documentation comment for a field.

Field Tags

An example of a field comment:

/**

     * The X-coordinate of the component.

     * @see #getLocation()

*/

    int x = 1263732;

Constructor and Method Documentation Tags

The following are the tags that can appear in the documentation comment for a constructor or method, except for @return, which cannot appear in a constructor, and {@inheritDoc}, which has certain restrictions. The @serialData tag can only be used in the doc comment for certain serialization methods.

Method/Constructor Tags

@throws and @exception

An example of a method doc comment:

/**

     * Returns the character at the specified index. An index

     * ranges from <code>0</code> to <code>length() - 1</code>.

     * @param     index  the index of the desired character.

     * @return    the desired character.

     * @exception StringIndexOutOfRangeException

     *              if the index is not in the range <code>0</code>

     *              to <code>length()-1</code>.

     * @see       java.lang.Character#charValue()

*/

    public char charAt(int index) {

...

}"

Running Javadoc the basic way (i.e. not through eclipse)

"RUNNING JAVADOC

Version Numbers - The version number of javadoc can be determined using javadoc -J-version. The version number of the standard doclet appears in its output stream. It can be turned off with -quiet.

Public programmatic interface - To invoke the Javadoc tool from within programs written in the Java language. This interface is in com.sun.tools.javadoc.Main (and javadoc is re-entrant). For more details, see Standard Doclet.

Running Doclets - The instructions given below are for invoking the standard HTML doclet. To invoke a custom doclet, use the -doclet and -docletpath options. For full, working examples of running a particular doclet, see Running the MIF Doclet.

SIMPLE EXAMPLES

You can run javadoc on entire packages or individual source files. Each package name has a corresponding directory name. In the following examples, the source files are located at C:\home\src\java\awt\*java. The destination directory is C:\home\html.

Documenting One or More Packages

To document a package, the source files (*.java) for that package must be located in a directory having the same name as the package. If a package name is made up of several identifiers (separated by dots, such as java.awt.color), each subsequent identifier must correspond to a deeper subdirectory (such as java/awt/color). You may split the source files for a single package among two such directory trees located at different places, as long as -sourcepath points to them both -- for example src1\java\awt\color and src2\java\awt\color.

You can run javadoc either by changing directories (with cd) or by using -sourcepath option. The examples below illustrate both alternatives.

Case 1 - Run recursively starting from one or more packages - This example uses -sourcepath so javadoc can be run from any directory and -subpackages (a new 1.4 option) for recursion. It traverses the subpackages of the java directory excluding packages rooted at java.net and java.lang. Notice this excludes java.lang.ref, a subpackage of java.lang).

·           % javadoc -d \home\html -sourcepath \home\src -subpackages java -exclude java.net:java.lang

To also traverse down other package trees, append their names to the -subpackages argument, such as java:javax:org.xml.sax.

Case 2 - Run on explicit packages after changing to the "root" source directory - Change to the parent directory of the fully-qualified package. Then run javadoc, supplying names of one or more packages you want to document:

·           C:> cd C:\home\src\

·           C:> javadoc -d C:\home\html java.awt java.awt.event

Case 3 - Run from any directory on explicit packages in a single directory tree - In this case, it doesn't matter what the current directory is. Run javadoc supplying -sourcepath with the parent directory of the top-level package, and supplying names of one or more packages you want to document:

·           C:> javadoc -d C:\home\html -sourcepath C:\home\src java.awt java.awt.event

Case 4 - Run from any directory on explicit packages in multiple directory trees - This is the same as case 3, but for packages in separate directory trees. Run javadoc supplying -sourcepath with the path to each tree's root (colon-separated) and supply names of one or more packages you want to document. All source files for a given package do not need to be located under a single root directory -- they just need to be found somewhere along the sourcepath.

·           C:> javadoc -d C:\home\html -sourcepath C:\home\src1;C:\home\src2 java.awt java.awt.event

Result: All cases generate HTML-formatted documentation for the public and protected classes and interfaces in packages java.awt and java.awt.event and save the HTML files in the specified destination directory (C:\home\html). Because two or more packages are being generated, the document has three HTML frames -- for the list of packages, the list of classes, and the main class pages.

Documenting One or More Classes

The second way to run the Javadoc tool is by passing in one or more source files (.java). You can run javadoc either of the following two ways -- by changing directories (with cd) or by fully-specifying the path to the .java files. Relative paths are relative to the current directory. The -sourcepath option is ignored when passing in source files. You can use command line wildcards, such as asterisk (*), to specify groups of classes.

Case 1 - Changing to the source directory - Change to the directory holding the .java files. Then run javadoc, supplying names of one or more source files you want to document.

·           C:> cd C:\home\src\java\awt

·           C:> javadoc -d C:\home\html Button.java Canvas.java Graphics*.java

This example generates HTML-formatted documentation for the classes Button, Canvas and classes beginning with Graphics. Because source files rather than package names were passed in as arguments to javadoc, the document has two frames -- for the list of classes and the main page.

Case 2 - Changing to the package root directory - This is useful for documenting individual source files from different subpackages off the same root. Change to the package root directory, and supply the source files with paths from the root.

·           C:> cd C:\home\src

·           C:> javadoc -d \home\html java\awt\Button.java java\applet\Applet.java

This example generates HTML-formatted documentation for the classes Button and Applet.

Case 3 - From any directory - In this case, it doesn't matter what the current directory is. Run javadoc supplying the absolute path (or path relative to the current directory) to the .java files you want to document.

·           C:> javadoc -d C:\home\html C:\home\src\java\awt\Button.java C:\home\src\java\awt\Graphics*.java

This example generates HTML-formatted documentation for the class Button and classes beginning with Graphics.

Documenting Both Packages and Classes

You can document entire packages and individual classes at the same time. Here's an example that mixes two of the previous examples. You can use -sourcepath for the path to the packages but not for the path to the individual classes.

  C:> javadoc -d C:\home\html -sourcepath C:\home\src java.awt C:\home\src\java\applet\Applet.java

This example generates HTML-formatted documentation for the package java.awt and class Applet. (The Javadoc tool determines the package name for Applet from the package declaration, if any, in the Applet.java source file.) "

Javadoc with Eclipse

http://jautodoc.sourceforge.net/

Follow this link for the download files for the javadoc eclipse plugin and for a brief explanation and screen shots of how it works.