Java Chinese document generation Javadoc use note

All Javadoc commands can only appear in the "/**" comment

There are two main ways to use Javadoc: embedded HTML, or use "document tagging ."

wherein, "document tags" (Doc tags) are some commands that start with "@", Placed at the beginning of the comment line (but the leading "*" is ignored).

Three types of annotation documents , which correspond to the elements that are located behind the comment: class, variable, or method. That is, a class comment is just before a class definition, and a variable comment is just before the variable definition, and a method definition is just before a method definition. As shown in the following simple example
:
/** A class comment */
public class Doctest {
/** a variable comment */
public int i;
/** a method Comment */
public void F () {}
}


Note Javadoc can only process comment documents for public and protected (protected) members. Comments for "private" and "friendly" members are ignored, and we don't see any output (you can also include private members with the-private tag). because only public and protected members can be used outside of the file.

embedding H T M L

Javadoc passes HTML commands to the resulting HTML document. This allows us to take full advantage of the great power of HTML. Of course, we
The ultimate motivation is formatting code, not for grandstanding. An example is listed below:

/*** <pre>* System.out.println (New Date ()); * </pre>*/

You can also use HTML as you would in other WEB documents to format plain text so that it is more organized and aesthetically pleasing:

/*** you <em> even </em> can insert a list: * <ol>* <li> Project One * <li> Project two * <li> Project three * </ol>*/

Note in the document comment, the asterisk at the beginning of the line is discarded by Javadoc.

There are also leading spaces discarded.

Javadoc all content in a format that matches the standard document appearance.

Do not use the title All types of annotation documents-classes, variables, and methods-support embedding HTML.

@ s E e: referencing other classes

All three types of comment documents can contain the @see tag, which allows us to reference documents in other classes. For this tag, Javadoc will
Generate the appropriate HTML and link it directly to other documents. The format is as follows:
@see class Name
@see Full class name
@see Full class name # method name

Each format automatically joins a hyperlinked "see Also" entry in the generated document. Note Javadoc does not check the hyperlinks we specify, and does not verify that they are valid.

Class Document Tags
Along with embedding HTML and @see references, class documents can also include markup for version information and author names. the class document can also be used for "interface" purposes.
1. @version
The format is as follows:
@version Version Information
Where "version information" represents any information that is appropriate for use as a version description. If the "-version" tag is used on the Javadoc command line, the published information is extracted from the generated HTML document.

2. @author
The format is as follows:
@author Author Information
The "Author information" includes your name, e-mail address, or any other appropriate information. If the Javadoc command line uses the "-
Author "tag, the author information is extracted specifically from the generated HTML document. You can use multiple such tags for a series of authors, but they must be placed continuously. All author information is stored together in a separate paragraph of the final HTML code.
Variable Document tags

The variable document can only include embedded HTML and @see references.


Method Document Tags


In addition to embedding HTML and @see references, the method also allows the use of document tags for parameters, return values, and violations.

1. @param
The format is as follows:
@param parameter Name Description
where "parameter name" refers to an identifier within a parameter list, and "description" represents some descriptive text that can be extended to subsequent lines. Once a new document tag is encountered, the previous description is considered to be complete. You can use any number of instructions, one for each parameter.

2. @return
The format is as follows:
@return Description
Where "description" refers to the meaning of the return value. It can be extended to a later line.

3. @exception
The format of the violation tag is as follows:
@exception Full class name description
Where the "full class name" explicitly specifies the name of an offending class, which is defined somewhere else. The "description" (which can also be extended to the following line) tells us why this particular type of violation occurs in a method invocation.
4. @deprecated
This is a new feature of Java 1.1. This flag is used to indicate that some of the old features have been superseded by the new features that have been improved . The purpose of this tag is to suggest that users no longer have to use a particular feature, as it may be discarded in future revisions. If you mark a method as @deprecated, you will receive a compiler warning when you use the method.
Documentation Examples

the following is our first Java program, except that we have added the full documentation comment:

: Property.javaimport java.util.*;/** The first thinking in Java example program. * Lists System Information on the current machine. * @author Bruce Eckel * @author http://www.  bruceeckel.com * @version 1.0*/public class Property {/** Sole entry point to Class & application * @param args array Of string arguments * @return No return value * @exception Exceptions No Exceptions thrown */public static void main (STR Ing[] args) {System.out.println (New Date ()); Properties p = system.getproperties (); P.list (System.out); SYSTEM.OUT.PRINTLN ("---Memory Usage:"); Runtime RT = Runtime.getruntime (); SYSTEM.OUT.PRINTLN ("Total memory =" + rt.totalmemory () + "free Memory =" + rt.freememory ());}} ///:~

The above content is referenced from thinking in Java , here to make a record, easy to view later.























  

Java Chinese document generation Javadoc use note