Alibaba Java Development Manual's Annotation Regulations and Javadoc Tags and Javadoc Annotation Specifications

Alibaba Java Development Manual's Annotation Regulations and Javadoc Tags and Javadoc Annotation Specifications

I recently looked at the source code, and sorted out some common comments in Javadoc

Javadoc is a technology provided by Sun. It extracts annotations such as classes, methods, and members from the program source code to form an API help document that matches the source code.

---

The Javadoc command is used to generate your own API documentation, using:

javadoc source file name.java
javadoc -d file storage directory source file
name.java generates Javadoc through IDEA: Tools -> Generate JavaDoc

javadoc tags

label	Description
@author	Author ID
@version	version number
@return	Description of the return value of the function
@deprecated	Identifies the expired API (to ensure compatibility, it is still available, but not recommended)
@throws	Exception thrown by constructor or method
@exception	同@throws
@see	Reference, view related content, such as classes, methods, variables, etc., must be written in the head
{@link 包.类#member}	Reference, same as @see, but can be written in any position
{@value}	For constant comments, if its value is included in the document, refer to the value of the constant by changing the label
{@code}}	{@code text} Mark the text as code and it will be parsed into text}. In Javadoc, as long as the class name or method name is involved, it needs to be marked with @code
@param	Description method parameters
@inheritDoc	Used to inherit the Javadoc in the parent class, the documentation comments of the parent class are inherited to the child class

javadoc comment specification

One, Java documentation

// 注释一行
/ *    */ 注释若干行  
/**   ……*/  注释若干行，写入Javadoc文档

2. Document format
The document annotations written on the category are generally divided into three paragraphs:

• The first paragraph: a summary description, usually a sentence or a paragraph to briefly describe the role of this type, ending with a period in English
• The second paragraph: a detailed description, usually one or more paragraphs are used to describe the function of this type in detail. Generally, each paragraph ends with a period in English
• The third paragraph: document annotation, used to mark the author, creation time, reference category and other information

生成文档是HTML格式。
换行<br>
分段<p>(写在段前）)

Example

/** 
* show 方法的简述.
* <p>show 方法的详细说明第一行<br> 
* show 方法的详细说明第二行 
* @param b true 表示显示，false 表示隐藏 
* @return 没有返回值 
*/ 
public void show(boolean b) {
    
    
    frame.show(b);
    } 

Notes on Alibaba Java Development Manual

1. Class, class attribute, class method annotation must use Javadoc specification, use /* content /format, not use //XX method.
2. All abstract methods (including methods in interfaces) must be annotated with Javadoc. In addition to return values, parameters, and exception descriptions, they must also indicate what the method does and what functions it implements.
3. All classes must add creator and creation date.
4. For single-line comments inside the method, start a new line above the commented statement and use // comment. For multi-line comments inside the method, use /* */ comments, pay attention to alignment with the code.
5. All enumeration type fields must have comments, explaining the purpose of each data item.
6. Instead of using unskilled English to annotate, it is better to use Chinese annotations to clarify the problem. Proper nouns and keywords can be kept in English.
7. While modifying the code, the comments must be modified accordingly, especially the modification of parameters, return values, exceptions, and core logic.
8. Comment out the code carefully. It should be explained in detail above, rather than simply commented out. If it is useless, delete it.
9. Requirements for comments:
   1) It can accurately reflect the design ideas and code logic.
   2) Be able to describe the business meaning so that other programmers can quickly understand the information behind the code. A large piece of code without comments at all is like a celestial book to readers; comments are for oneself to see, and it should be possible to clearly understand the thinking at the time even if there is a long interval. Comments are also for successors to see so that they can quickly Take over your own work.
10. Good naming and code structure are self-explanatory, and comments strive to be concise and accurate, and express in place. One extreme of avoiding comments: excessive comments, because once the logic of the code is modified, modifying the comments is a considerable burden.
11. For special annotation marks, please indicate the person and time of the mark. Pay attention to handling these marks in a timely manner, and often deal with such marks through mark scanning. Sometimes the online fault comes from the code at these marks.