"Reprint" Javadoc study notes and possible attention to detail

Reprinted from: http://www.cnblogs.com/xt0810/p/3630996.html

"Previous words."

The development project uses Jenkins to do continuous integration, PMD check code, JUnit do unit testing, and automatically send email notification of compilation, will automatically send Javadoc generated documents to a dedicated server, everyone can see, So I have to do a good study of Javadoc, others can see also beautiful.

"Basic Knowledge"

First, JavaDoc Introduction and Fundamentals

(i) Java annotation type

1. Used for single-line comments.
2. The/*...*/is used for multiline annotations, starting from/* and ending with */, not nested.
3. /**...*/is a comment statement that is unique to support the JDK tool Javadoc.exe.

Description: The Javadoc tool can read a third comment from the Java source file and recognize some special variables (see table) identified in the annotation, and make the class description document in HTML format. Javadoc can not only generate annotated documents for a Java source file, but also facilitate the creation of a cross-linked HTML-formatted class description document for directories and packages.

Two The @ character that appears in Javadoc and its meaning:

1. General notes

annotations can be The current keyword starts with @
@author
	version ID
@since
@deprecated
	Cross reference

2. Method notes

@return	return value
@throws	Exception classes and throwing conditions
@param	The name of the parameter and its significance

(c) Give an example:

We define a Bustestjavadoc class to specify the specification of annotations when using the Javadoc command.

1. There are 4 properties of the car class:

1) maxspeed--Maximum speed

2) averagespeed--Average speed

3) watertemperature--Water temperature

4) temperature--room temperature

2. Two methods:

1) measureaveragespeed ()--average speed of the car

2) Measuremaxspeed ()--Max speed

3.bustestjavadoc.java Example:

1/** 2 * Introduction of automotive Class 3 *<p> Automotive class specific description first line <br> 4 * Automotive class details of the second line 5 * @author man 6 * @author man2 7 * @version 1.0 8 * @see ship 9 * @see aircraft10 */11 public class bustestjavadoc{12     /**13     * is used to identify the maximum speed of the car     @see #averageSpeed15     The */16 public     int maxspeed;17     /** is used to identify the average speed of the car driving */18 public     int averagespeed;19/**     used to identify the water temperature in the car's travel */20 public     int watertemperature;21     /** used to identify the weather temperature */22 public     int temperature;23     Bustestjavadoc () {24         +     }     /**27      * This method is used to measure the average speed in a period of time *      @param start start time      * @param end cutoff time      * @return return int type variable 31      * @exception java.lang.exceptionthrowwhenswitchis132      */33 public     int measureaveragespeed (int start, int end) {         aspeed;36 int aspeed=12;35         return         }37     /**38      * This method is used to measure the maximum speed of the      */40     public int measuremaxspeed () {         return maxspeed;42     }44}

4. Export HTML documents in eclipse:

export--java--javadoc--Choose the storage location, you can look at the production of Javadoc

Second, Javadoc a few comments

(i) Class notes

Class annotations appear after the import statement, and before the class definition, you can use common annotations, as follows:

1/** 2 * Introduction of automotive Class 3 *<p> Automotive class specific description first line <br> 4 * Automotive class details of the second line 5 * @author man 6 * @author man2 7 * @version 1.0 8 * @see ship 9 * @see aircraft10 */11 public class bustestjavadoc{12}

(ii) Methodological notes

Each method comment must precede the described method, and you can use a method comment in addition to the generic comment. As follows:

1/** 2      * This method is used to measure the average speed over time 3      * @param start start time 4      * @param end cutoff time 5      * @return return int variable 6      * @exception J AVA.LANG.EXCEPTIONTHROWWHENSWITCHIS1 7      */8 public int measureaveragespeed (int start,int end) {9         int aspeed=12; Ten         return aspeed;11         }

(iii) Domain annotations

Just comment on the public domain, and you can use common annotations, as follows:

1/**2     * Used to identify the maximum speed of the car 3     * @see #averageSpeed4     */5 public     int maxspeed;

(iv) Package annotations and overview notes

For classes, methods, the comment of the variable is placed in the Java source file, just use the/** */document comments are defined, if you want to annotate the package, you need to add a separate file in each package directory. As follows:

1. Provides a package.html-named HTML document. Mark <body> All text between </BODY> will be extracted.
2. Provides a package-info.java-named Java file. This file must contain an initial/** and/* defined Javadoc annotation, followed by a package statement. No more code or comments should be included.

If you want all the source files to have an overview comment, provide a overview.html-named HTML document. This file is located in the parent directory that contains all the source files. Mark <body> All text between </BODY> will be extracted.

Third, document comments and HTML

(i) HTML format generation:

The generated documents are HTML styles, and the identifiers for these HTML styles are not Javadoc, but written when they are interpreted. For example, instead of typing in 1 carriage returns, you need to write
, and if you want to fragment, you should write to

before the paragraph.

Thus, formatting a document is nothing more than adding the appropriate HTML tag to the document interpretation.

The body of the document comment is not copied directly to the output document (the document's HTML document), but after each line is read out, the leading * number and the * number of the previous space are deleted and then entered into the document.

(b). In the Java documentation, this is:

1/** *thisisfirstline.<br>2 *****thisissecondline.<br>3 thisisthirdline. 4 */

(c) After compiling the output of the HTML source code is:

1 thisisfirstline. 
 2 thisissecondline. 
 3 thisisthirdline.

(d) This is shown on the webpage:

Thisisfirstline.thisissecondline.thisisthirdline.

(v) Description:

The leading * number allows for the continuation of more than one, the results and the use of 1 * number consistent, but not only one * number can not be separated by other characters, or separators and behind. The * number will be used as the document content. The * number is used here as the left border, as in the first and second lines of the preceding example; if there is no leading * number, the frontier begins with the first valid character and does not include the preceding space, as in the previous example, line fourth.

Four, documentation Notes attention to detail

The document interpretation clarifies only the classes, attributes, or methods immediately following.

(a) The following example:

1/**comment for class*/2 public class test{3/**comment for a attribute*/4 int number; 5/**comment for a method*/6 p ublic void MyMethod () {...} 7    

The three interpretations in the above example are different from the document interpretation of classes, properties and methods. The documents they generate are the classes, properties, and methods that are immediately followed. The word "immediately" is particularly important, and if this is overlooked, it is likely that the resulting document will fail.

(b) The correct example

(c) Examples of errors:

This example only places the import statement and the document interpretation of the above example in a local exchange, the effect is not the same-the resulting document is basically unable to find the above interpretation of the content.

(d) Cause of the error:

The "/**comment for class*/" System clarifies the Test class by placing it in "public class test{...}" Before, followed by class Test, which matches the qualification, so the resulting document is accurate. But put it and "importjava.lang.*;" After changing the position, the class test is not immediately followed, but an import statement. because a document interpretation can only clarify classes, attributes, and methods, Import statement is omitted, so the interpretation of this document is interpreted as a failure.

Five, three parts of a document comment

Based on the final display of the document format on the page, the document comments are divided into three sections:

(i) examples

1/** 2      * This method is used to measure the average velocity over time. 3 *<p> ah ah ah ah      <br> 4      *<p> haha haha <br> 5      * @param Start start time 6      * @param end cutoff Time 7      * @return return int type variable 8      * @exception java.lang.exceptionthrowwhenswitchis1 9      */10 public     int measureaveragespeed (int start,int end) {One         int aspeed=12;12         return aspeed;13}

(ii) Part I: Brief description.

In the HTML display, the properties and methods are outlined first.

The second sentence in the above example--* the method to measure the average speed over time.

Through. To make a distinction, in the brief section only shows the part before the. Number. For example, the Measureaveragespeed method only shows that the method is used to measure the average speed over a period of time. The words, "Ah ah ah ah ah ah" "ha haha haha" are not shown.

(iii) Part II: Partial clarification of attributes or methods

Clarify the Java statement:

1  * This method is used to measure the average speed over a period of time. 2 *<p> ah ah ah <br>3 *<p> haha haha haha  <br>

Include the statements in the brief, such as:

(iv) Part III: Special Instructions

Java statements:

1 * @param start start time 2 * @param end cutoff time 3 * @return return int Variant 4 * @exception JAVA.LANG.EXCEPTIONTHROWWHENSWITCHIS1

Such as:

Six, using Javadoc notation

(a) Application of @see

1. Provide the class name, method name, variable name, Javadoc insert a hyperlink in the document. As follows:

@see com.cn.corejava.bustestjavadoc#measureaveragespeed (int)

Create a hyperlink to the Measureaveragespeed (int) method that is linked to the Com.cn.corejava.BusTestJavaDoc class.

Note: it must be # to split the class and method names or the class name and variable name.

2. @see <a href= "www.baidu.com" > Baidu </a>

(ii) Use of @author, @version clarify the class

1. @author, there can be more than one
2. Only one better.

(iii) Use of @param, @return and @exception to clarify the way

1. These three marks are all used for methods only . @param descriptive way of the parameters, @return descriptive way of the return value, @exception descriptive way may throw the exception.
2. Each @param can only describe the 1 parameters of the way, so if the method requires more than one parameter, it needs to be described more than once using @param.
3. @return The following code: Only 1 @return can be used in a single way, and if more than one @return is listed in the document clarification, the Javadoc will emit a warning when compiling, and only the first @return in the generated document will be generated in the first one. The following is the first one generated:

1 * @return return int type variable 2 * @return return double type variable

4. The method may throw an exception that should be described in @exception. Because one way might throw more than one, so there can be more than one @exception

Seven, Javadoc Command

A Javadoc Generate command

1. Javadoc command

javadoc-d Document storage directory-author-version the directory \ Source file name exists in the Java document. java

-author–version can be omitted

2. For example:

Java-d D:\workspace8\JavaDoc\src D:\workspace8\JavaDoc\src\BusTestJavaDoc.java

3. For example:

Two Javadoc help command

Run Javadoc-help to see the usage of Javadoc, as follows:

"Recommended Style"

First, Format

• General form:

Such

/** * Multiple lines of Javadoc text is written here, * wrapped normally ... */public int method (String p1) {...}

or this:

/** a especially short bit of Javadoc. */

• Paragraph

Blank lines (that is, rows that contain only the leftmost asterisk) appear between paragraphs and before the Javadoc tag (@XXX), if any. In addition to the first paragraph, each paragraph has a label before the first word <p> , and there are no spaces between it and the first word.

• Javadoc Mark

The standard Javadoc tags appear in the following order:,,, @param @return @throws @deprecated before these 4 kinds of tags appear, the description cannot be empty. When the description cannot be accommodated in a row, successive lines need to be indented at least 4 more spaces.

Ii. Summary Fragments

• The Javadoc of each class or member begins with a short digest fragment. This fragment is very important, and in some cases it is the only text that appears, such as in the class and method indexes.
• This is just a small fragment, can be a noun phrase or a verb phrase, but not a complete sentence. It will not be a {@code Foo} is a ... Or This method returns ... At the beginning, it will not be a complete imperative, such as the Save the record .... However, it looks like a complete sentence because it is capitalized and punctuation is added.
• TIP: A common mistake is to write a simple Javadoc /** @return the customer ID */ , which is not true. It should be written /** Returns the customer ID. */ .

Third, where to use Javadoc

Use Javadoc at least for each public class and every public and protected member of it.

Exception:

• Self-explanatory method

For simple and obvious methods such as Getfoo,javadoc is optional (i.e., can not be written). In this case, in addition to writing "Returns the Foo", there is really nothing worth writing about.

The test methods in the unit test class are probably the most common examples of self-evident, and we can usually tell from the descriptive naming of these methods what it does, so no additional documentation is required.

• Overload

If a method overloads a method in a superclass, then Javadoc is not required.

• Optional Javadoc

For classes and methods that are not visible outside the package, you also want to use Javadoc if necessary. If a comment is used to define the overall purpose or behavior of a class, method, field, then this annotation should be written as Javadoc, which is more uniform and friendlier.

Resources

1. This article is mainly to learn the "javadoc__ usage _ very detailed" This document

"Behind the words."

Come on.

"Reprint" Javadoc study notes and possible attention to detail