Introduction to javadoc specification

Introduction:

We know that javadoc is embedded in the JDK, so following the javadoc specification is definitely the orthodoxy of java annotations. Generating API documentation with the help of javadoc is Very practical.

(Learning video sharing: java video tutorial)

1. What are comments

Comments are to make the code more It is readable and reduces the communication cost of teamwork. In a team, if your code is clearer, more readable, and more standardized, then promotion and salary increase will definitely be yours, because you can be compatible with more people.
I heard a saying some time ago: If only you can understand your code, then you are the indispensable person. The person who said this is stupid. Only he can read and understand the code he writes. No one wants to see him. He lives like a grandson. Does everyone need a grandson?

2. Commonly used comment shortcut keys

Comment a line: //I am the content of the line
Shortcut key: ctrl/Reverse operation: ctrl/Comment a block:/*I am the content of the block* /
Shortcut key: ctrl shift / Reverse operation: ctrl shift \javadoc Recognizable comments:

	/**
	 * 我是注释
	 * 我也是注释
	 * 我还是注释，我们都能被javadoc识别
	 */

3, javadoc specification

Follow the javadoc specification, we can use the javadoc command, It is very convenient to generate very intuitive and easy-to-read API documents.
The comments we appear in the program can be divided into two types consciously, one is simple comments for ourselves to see, and the other is comments that comply with the javadoc specification, with the purpose of generating easy-to-read documents.
Read the generated API document carefully. There are three parts that need our explanation, as shown in the figure:

##The contents of the red box above are all comments I added. It is a simple Hello class. The source code is as follows. If you are interested, you can try it yourself:

/**
  *	@author XXXX
  *	@version 创建时间：2021年1月21日 下午3:22:01
  *	
  */
public class Hello {

	/**
	 * main()方法简述(后面这个dot必不可少).
	 * <p>这就是为了测试注释<br>
	 * 没什么好说明的，只为了说明能出现在这里
	 * @param args 就是系统配的，没啥说的
	 * 
	 */
	public static void main(String[] args) {
//		 TODO Auto-generated method stub
		System.out.println("hello");	

	}
	
	/**
	 * havaReturn方法就是为了测试javadoc注释规范的.
	 * <p>我发现只有有返回值的方法才可以使用return标签<br>
	 * 没有return硬是要用，只会在javadoc时候报错
	 * @param a 输入的第一个int类型的参数
	 * @param b 输入的第二个int类型的参数
	 * @return add 两个数的和运算结果
	 */
	public int haveReturn(int a,int b){
		int add=0;
		add=a+b;
		return add;
	}

}

There are several points that need to be pointed out:

If you want the author and version to appear in the API document, you must not only add @author and @version in the program comments (it should be noted that annotating @author in multiple places in the program will only be displayed once in the final document. I recommend only comment once), and also point it out in the dos command when compiling:

javadoc -d folder -version -author Hello.java
where -d folder means you put the generated API document (actually many web pages (composed) in a folder folder. Of course, the folder can also be a path.

How to distinguish between method summary and method details?

/**
	 * main()方法简述(后面这个dot必不可少).
	 * <p>这就是为了测试注释<br>
	 * 没什么好说明的，只为了说明能出现在这里
	 * @param args 就是系统配的，没啥说的
	 * 
	 */
	public static void main(String[] args) {
//		 TODO Auto-generated method stub
		System.out.println("hello");	

	}

You must have found that there are a lot of comments about methods. How does javadoc extract the summary? That's right, just rely on one dot(.), observe the dot mentioned in my comment, that is the key to extract the summary. The dot is preceded by the summary, and everything is a detailed introduction (the detailed introduction includes the summary)

How to control the typesetting of comments in generated documents

What we can control in the program is the typesetting of comments, but this typesetting is not recognized by javadoc. Javadoc finds a line of comments and only removes * and spaces. , I just passed it over and noticed that the generated document is of HTML type, so as long as you comment the HTML syntax in the program, you can edit the API document format. Don't worry about it being too difficult, because we just use some simple HTML syntax, such as paragraphs.

, newline
these are enough, after all, the comments will not be very long.

@param parameter 1 description (note the format)

@return return value description (note the format)

If there is a return value, write it. If there is no return value, you don’t need to write it. If you write it, it will Error reporting

In fact, writing class comments and method comments is very simple. Just type /** in front of the class and method, and then press Enter, the system will automatically add it, and we can modify how the system adds it

How to modify the content that appears when creating a new file, how to make the automatically completed comments under our control (to be done)

We see this from the standard class file:

We all know that out is an attribute (field) of the System class, which is of type PrintStream. There are many methods defined in the PrintStream class. These are naturally out methods, so when defining out , there are a lot of @see in the comments in front of it. This is the best place to use @see annotation. We recommend that when defining the fields of a class, if the field is a composite type (especially a custom composite type), then Note @see in front, this has two advantages, please see the picture:

I believe you are familiar with these two pictures. The first one is a prompt that appears when the cursor stays when writing a program. If you write comments according to the javadoc specification, then you wrote it yourself. The program also appears with these extremely helpful prompts. The second is the detailed description of the out field in the String class in the Java8 API document. This is also the credit of @see. You wrote @see, and there is such annotation in your own project API document.

Related recommendations: java introductory tutorial

The above is the detailed content of Introduction to javadoc specification. For more information, please follow other related articles on the PHP Chinese website!