When we create a new class, we often forget to write or are too lazy to write Javadoc related comments, which is not conducive to the readability of our code, and will greatly increase the maintenance cost of the project, so we can use the Intellij IDEA tool to automatically generate standard Template comments are convenient for later maintenance, and the entire JavaDoc document can be generated with one click. Next, Teacher Pan will show you how to implement it.

1.Configuration template

We open: File -> Settings, and the "Setting dialog box" pops up

2.Find File -> Settings -> Editor -> File and Code Templates -> Includesand edit the FileHeadertemplate as follows:

/**
* <h3>${PROJECT_NAME}</h3>
* @description
* <p>${description}</p>
* @author panziye
* @date ${YEAR}-${MONTH}-${DAY} ${HOUR}:${MINUTE}
**/

Tip: You can set it according to your own needs and rules

The specific instructions are as follows:

Note: The template here is valid for all new java related files ( as shown in the figure below ) by default , because they all reference FileHeader.java, so you can also make special template customization for classes or interfaces, etc.

3.When we TestDemo1create a new project in the project Class(I named the class here TestDocand put it in the package), we will find one more step to enter the description: 4.After the creation is successful, its structure is as follows (I added the main method):

2.Generate JavaDoc with one click

1.Open the Tools -> Generate JavaDocconfiguration as follows:

- Tag DATE : A : Date - Tag Description : A : Description - encoding UTF - . 8 - charset UTF - . 8

Note: If you have a custom javadoc tag, you need to enter the definition in the other command line arguments box, for example: -tag date:a:date-tag description:a:description-encoding UTF-8 -charset UTF-8 to specify Undefined annotations and the specified document encoding are UTF-8, otherwise an error may be reported

2.The generated documents are as follows:

3.Double-click the index.htmlbrowser to open
(ignore the package name, the format is wrong) and click to open the category:

3.JavaDoc plugin

In fact, we can also use the JavaDoc plug-in to help us effectively manage JavaDoc documents.It should support the automatic generation of annotation templates for corresponding methods, formal parameters, return values, etc.However, I am interested here because the IDEA version is too low and the installation fails.It can be Settings -> Pluginsinstalled and used in China, so I won't repeat it here.

4.Supplementary explanation

Common JavaDoc annotations:

Alibaba JavaDoc constraint rules:

Notes on the Alibaba Java Development Manual:

Class, class attribute, class method annotation must use Javadoc specification, use /*content/format, not use //XX method.

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.

All classes must add the creator and creation date.

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.

All enumeration type fields must have a comment, explaining the purpose of each data item.

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 the original English language.

While modifying the code, the comments must be modified accordingly, especially the modification of parameters, return values, exceptions, and core logic.

Comment out the code carefully. It should be explained in detail above, rather than simply commented out. If it is useless, delete it.

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.

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 and excessive comments, because once the logic of the code is modified, modifying the comments is a considerable burden.

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 online faults originate from the codes at these marks.