This section focuses on the javadoc tags that we often use, which are relatively simple, but can really make our code look great if used correctly. Not only that, but as long as we follow the Javadoc comment rules, Javadoc can also help us generate htML-formatted API development documentation from the source code after coding. You can click on the Oracle specification and I have sorted the commonly used Javadoc tags according to your own habits, as shown below:
tags
When adding comments to public classes or methods, the first sentence should be a short summary. Make sure there is no asterisk on the left, there should be a space. If the comment has multiple paragraphs, use the < p> paragraph tag to separate the paragraphs. We can also use the < tt> tag to make certain content appear as text with equal width. See below:
/** * The first sentence is the short summary of the method. * If the description is too long, remember to wrap it. * * If multiple paragraphs can do this * when the carriage return is aligned with the header of the tag */
public void test(a){}
Copy the codeIf the description of a comment needs to include a list, a list of options, etc., we can use the < li> tag to identify it. Note that no space is required after the tag, as shown below:
/** * The first sentence is a short summary of the method. * If the description is too long, remember to wrap it. * * < p > if multiple paragraphs can be such a * * * < li > < ul > this is a list of 1 * < li > this is a list of 2... * */
public void test(a){}
Copy the code@param is the input parameter used to describe the method. Note that a blank comment line needs to be inserted between the method description and the tag. It is not necessary to align the description of each parameter param, but ensure that multiple lines of the same param are aligned. Param’s description does not need to be punctuated at the end of the sentence.
/** * The first sentence is a short summary of the method. * If the description is too long, remember to wrap it. * *@paramBuilderTest adds the description of the argument. If the description is very long, you need to press Enter@paramIsTest adds a parameter description that does not need to be aligned with other param * parameters */
public void test(String builderTest, boolean isTest){}
Copy the code@return is used to describe the return value of a method. To write after the @param tag, no line breaks are needed between other tags. @throws specifies the exception that may be thrown by the opposing method. The format is: Name of the exception class + reason why the exception occurs in the method. See below:
/** * The first sentence is a short summary of the method. * *@paramCapacity Adds a parameter description. You do not need to align it with other param parameters@returnDescribes the meaning of the returned value, can be multiple lines, does not need to end with a period *@throwsIllegalArgumentException If the initial capacity is negative * <ul> * <li> This is condition 1 (not required) to throw an exception, note the <li> format * </ul> *@throwsNote that if there are other exceptions to the method, multiple */'s are allowed
public int test(int capacity){
if (capacity < 0)
throw new IllegalArgumentException("Illegal initial capacity");
return capacity;
}
Copy the code@deprecated is used to indicate that some old features have been replaced by new and improved features and to advise users not to use the old features. It is often used in conjunction with @link. Of course, there is no limit to where @link can be used, but when our description needs to refer to other classes or methods, we can use @link. Javadoc generates hyperlinks for us:
/** * The first sentence is a short summary of the method. * If the description is too long, remember to wrap it. * *@deprecatedNot recommended from version 2.0, replace with {@link #Test2()}
* @paramIsTest adds a parameter description that does not need to be aligned with other param * parameters */
public void test(boolean isTest){}
Copy the code@link See below for common forms:
@code is used to mark a small piece of equal width font. It can also be used to mark a class or method, but no hyperlinks are generated. Often in conjunction with @link, the first hyperlink is generated through @link, and then the uniform width font is rendered through @code.
/** * The first sentence is a short summary of the method. * We can associate {@linkTest} class, followed by {@code* You can also mark a method {@code request()}
*
* @paramIsTest adds a parameter description that does not need to be aligned with other param * parameters */
public void test(boolean isTest){}
Copy the code@see is used to refer to documents of other classes. As a hyperlink, Javadoc links the @see tag to other documents in the HTML file it generates:
/** * The first sentence is a short summary of the method. * *@paramCapacity Adds a parameter description. You do not need to align it with other param parameters@returnDescribes the meaning of the returned value, can be multiple lines, does not need to end with a period *@throwsIllegalArgumentException If the initial capacity is negative *@see com.te.Test2
* @see #test(int)
*/
public int test(int capacity){
if (capacity < 0)
throw new IllegalArgumentException("Illegal initial capacity");
return capacity;
}
Copy the code@see form is similar to @link, see below:
/** * The first sentence is a short summary of the class. * <pre> * Test<Test2> t = new Test<>(); * </pre> * * <p> * *@param<T> Note that when a class uses generics, we need to use params. At this point the format needs to insert a blank line * *@author mjzuo [email protected]
* @see com.te.Test2
* @version 2.1
* @since2.0 * /
public class Test<T extends Test2> {
/** * The first sentence is a short summary of the method. * *@paramsCapacity Description of the parameter *@returnA description of the returned value *@since2.1 * /
public int test2(int capacity) {
returncapacity; }}Copy the code@inheritDoc inherits documentation from the current class’s most direct base class to the current documentation comment. The test() method below directly inherits the test() method annotation of the class’s immediate parent. Note that there is no need to insert blank lines with other tags:
/ * * * {@inheritDoc}
* @since2.0 * /
public void test(boolean isTest){}
Copy the codeDocRoot It always points to the root of the document, representing a relative path from any generated page to the root of the generated document. For example, we can add a copyright link to each generated document page, assuming that our copyright page, copyright.html, is in the root directory:
/**
* <a href="{@docRoot}/copyright.html">Copyright</a>
*/
public class Test {}
Copy the code@hide When using Doclava provided by Google, we can use @hide to mask methods that we don’t want exposed in the javaDoc documentation.
/ * * * {@hide} * /
public class Test {}
Copy the codeOk, this concludes the article’s introduction to the commonly used javaDoc tag. If this article is useful to you, give it a thumbs up, everyone’s affirmation is also the motivation of dumb I to keep writing.