How to write a beautifully formatted Javadoc?

If you have read Java source code, then you should have seen the source of beautiful Javadoc. In eclipse, the mouse pointer to any public method will show a detailed description, such as return value, action, exception type, and so on.

This article is mainly from "Thinking in Java" content and I write Javadoc experience in the work.

Three types of annotation documents

There are three types of note documents that correspond to the three elements that follow the comment location: classes, fields, and methods. It is also said that the class comment precedes the class definition; the domain comment precedes the domain definition, and the method comment is before the method definition. ：

//: object/Documentation1.java/** 类注释 */publicclass Documentation1 {    /** 域注释 */    publicint i;    /** 方法注释 */    publicvoidf///:~

Note that Javadoc can only document comments for public and protected members. Comments for private and accessible members within the package are ignored, so they are not visible in the output. If you want to see in the output results, you can use -private to mark it. This is done because only public and protected members can be used outside of the file. The HTML document generated by the above code can be viewed in a browser.

Embedded HTML

Javadoc sends HTML commands through the generated HTML document, which allows you to take full advantage of HTML.

/*** <pre>* System.out.println(new date())* </pre>*////:~

We can also see from the above comments that the annotations are output, so this code will be available System.out.println(new date()) .

You can also format annotations with HTML code:

/*** You can <em>even</em> insert a list:* <ol>* <li> item one* <li> item two* <li> item three* </ol>*////:~

Note that the contents of each planetary and subsequent spaces are not exported to the document, and do not use title tags in Javadoc, for example

Or. This is because Javadoc will insert its own title, and your title may conflict with them.

Javadoc label

[email protected]: referencing other classes

* * @see * * Tags allow users to reference documents from other classes. Javadoc is linked to other documents through the * * @see * * tag in its generated HTML file. The format is as follows:

@see 类名@see 完整类名@see 完整类名#方法名

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.

2.{@link package.class#member Label}

This tag is very similar to @see, except that it is used for inline, and is used as a "label" for hyperlinked text without "see Also".

3.{@docRoot}

The label produces a relative path to the document root, and is used for the display hyperlink on the document Tree page

4.{@inheritDoc}

The tag inherits the relevant document from the most direct base class of the current class into the current document comment.

5. @version

The format is as follows:

@version version-information

Where "version-information" represents any information that is appropriate for use as a release note. If the "-version" tag is used on the Javadoc command line, the published information is extracted from the generated HTML document.

6. @author

The format is as follows:

@author author-information

where "author-information" includes your name, e-mail address or any other appropriate information. If the "-author" tag is used on the Javadoc command line, 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.

7. @since

This tag allows you to specify the earliest version of the program code, which you can see in the HTML Java document that it is used to specify the version of the JDK you are using.

8. @param

The label is used in the method document and is exercised as follows:

@param

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.

9. @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.

Ten. @throws

The format is as follows:

@throws fully-qualified-class-name description

where fully-qualified-class-name description gives an unambiguous name for an exception class, and the exception class is defined elsewhere. Description tells you why this particular type of exception will appear in the method call.

[Email protected]

Some of the old features used in this tag have been superseded by the improved new features, and it is recommended that users stop using these old features because they are likely to be removed in the near future. If you use a method that is marked @deprecated, it causes the compiler to publish a warning.

Source code Example

Let's take a look at equals how the notes for the methods in JDK8 are written:

/*** Compares this string to the specified object. The result is {@code* true} if and only if the argument are not{@code null}and is a {@code* String} object that represents the same sequence of characters as this* object.     *     * @param AnObject* The object to compare this{@code String}against     *     * @return {@code true}if the given object represents a{@code String}* Equivalent to this string,{@code false}otherwise     *     * @see #compareTo (String)     * @see #equalsIgnoreCase (String)     */     Public Boolean equals(Object AnObject) {if( This= = AnObject) {return true; }if(AnObjectinstanceofString) {String anotherstring = (string) anobject;intn = value.length;if(n = = anotherstring.value.length) {CharV1[] = value;Charv2[] = anotherstring.value;inti =0; while(n--! =0) {if(V1[i]! = V2[i])return false;                i++; }return true; }        }return false; }

Take a look at the display in Eclipse.

**{@code}** Before the introduction, the actual display effect is easy to see, that is, the space after the content of the code to display the style.

Writing concise, easy-to-maintain annotations requires long-term practice. In addition to the conscious use of javadoc outside the work, reading the source code, the code to imitate the notation is also a good choice.

How to write a beautifully formatted Javadoc?