Javadoc Standard Summary(Javadoc规范整理）

1.Three types of comments in Java
1) //
Comment on single line.
2) /* – */
Comment on several lines.
3）/* – /
Comment on several lines and write in javadoc.

2.Generating Java Doc
1）In command
javadoc -d filepath -author -version filename.java
filepath : the target storage path of the javadoc
filename : the name of the file
-author and -version are optional.
2) In Eclipse
Right click on the project name, choose ‘Export…’, then a window appears as shown in fig-1. Choose Javadoc. Then next.

fig-2 : You can configure Javadoc command and change the destination of the storage path of the doc. You can also choose which level of the code to generate, public is default, if private chosen, doc will be generated for all levels. Then next.

fig-3 : You can change doc title here. Then next.

fig-4 : You can add VM options here. Then finish.

fig-5 : Go to the file path, you will see doc already generated. Open the index.html in browser and you’ll see the complete javadoc.

3.Formatting of the doc and annotation
A) Syntax
Javadoc follow the syntax of HTML. So we use HTML tags to format the doc. For example:
1) <br> – change line instead of Enter
eg.
/**
* First line. ＜br＞
* Second line. ＜br＞
* Third line.
*/
2) <p> – a paragraph
eg.
/**
* A BeanDescriptor provides global information about a “bean”,
* including its Java class, its displayName, etc.
* <p>
* This is one of the kinds of descriptor returned by a BeanInfo object,
* which also returns descriptors for properties, method, and events.
*/

NOTE
A document annotation only indicates the class, attribute, or method immediately following it. For example:

RIGHT as below
/* comment for class /
public class Test {
/* comment for a attribute /
int number;
/* comment for a method /
public void myMethod() {
……
}
……
}

WRONG as below
/* comment for class /
import java.lang.*;
public class Test { …… }

B)Three components of the javadoc comment
The example goes first:
/**
* Brief info of the method.
* ＜p＞Detailed info, line 1＜br＞
* Detailed info, line 2
* @param b true indicates show，false indicates hide
* @return no return parameters
*/
public void comp(boolean b) { frame.show(b); }

Part 1 : Brief info of the method. It is separated from Part 2 by a dot(‘.’).

Part 2 : Detailed info. It can have several paragraphs(several dots).

Part 3 : Special instructions including version, parameters, return and so on. As we can see in the example above, @param shows the input parameter, @return shows the output parameter. There are also many other tags in Javadoc.