Javadoc tag and Javadoc annotation specification
- 2021-08-16 23:57:46
- OfStack
Look at the source code recently, 1 some common comments of Javadoc are sorted out
Javadoc is a technology provided by Sun Company, which extracts annotations such as classes, methods and members from the program source code to form an API help document matched with the source code.
The Javadoc command is used to generate your own API document, using:
javadoc source filename. java
javadoc-d document storage directory source filename. java
Generate Javadoc from IDEA: Tools- > Generate JavaDoc
javadoc Tag
标签 | 说明 |
---|---|
@author | 作者标识 |
@version | 版本号 |
@return | 对函数返回值的描述 |
@deprecated | 标识过期API(为了保证兼容性,仍可用,但不推荐用) |
@throws | 构造函数或方法会抛出的异常 |
@exception | 同@throws |
@see | 引用,查看相关的内容,如类,方法,变量等,必须顶头写 |
{@link 包.类#成员} | 引用,同@see,但可写在任意位置 |
{@value} | 对常量注释,如果其值包含在文档中,通过改标签引用常量的值 |
{@code}} | {@code text}将文本标记为code,会被解析成 text } ,在Javadoc成只要涉及到类名或者方法名,都需要使用@code进行标记 |
@param | 说明方法的参数 |
@inheritDoc | 用于继承父类中的Javadoc,父类的文档注释,被继承到了子类 |
javadoc annotation specification
1. Java document
// Notes 1 Row
/ * */ Note several lines
/** ... */ Comment several lines and write Javadoc Document
2. Document format
The document annotation 1 written on the class is generally divided into three paragraphs:
Paragraph 1: Summary description, usually a brief description of the role of this class in one sentence or one paragraph, ending with an English full stop
Paragraph 2: Detailed description. Usually, one or more paragraphs are used to describe the role of this class in detail. Generally, each paragraph ends with an English full stop
Paragraph 3: Document annotation, which is used to annotate the author, creation time, reference class and other information
The generated document is HTML Format.
Line break <br>
Segment <p>( Write before the paragraph) )
Example
/**
* show Brief introduction of method .
* <p>show Detailed description of the method 1 Row <br>
* show Detailed description of the method 2 Row
* @param b true Represents the display, false Indicates hiding
* @return No return value
*/
public void show(boolean b) {
frame.show(b);
}
Supplement: 3 annotations of Java Javadoc markup *
Three annotation methods:
1. Single-line comment//Content of comment
2. Multi-line annotation/* ......*/
3, /**...... */, this way is similar to the second way. This format is for the javadoc program to automatically generate documents.
The label of Javadoc under 1 is described below:
JavaDoc 标 记 |
解释 |
@version |
指定版本信息 |
@since |
指定最早出现在哪个版本 |
@author |
指定作者 |
@see |
生成参考其他的JavaDoc文档的连接 |
@link |
生成参考其他的JavaDoc文档,它和@see标记的区别在于,@link标记能够嵌入到注释语句中,为注释语句中的特殊词汇生成连接。 eg.{@link Hello} |
@deprecated |
用来注明被注释的类、变量或方法已经不提倡使用,在将来的版本中有可能被废弃 |
@param |
描述方法的参数 |
@return |
描述方法的返回值 |
@throws |
描述方法抛出的异常,指明抛出异常的条件 |
Special statement:
(1) javadoc generates annotation documents for public classes
(2) javadoc can only be over methods or attributes modified by public or protected
(3) Formatting of javadoc annotations: Leading * sign and HTML tag
(4) javadoc comments should only precede classes, properties and methods
The following is a main example to illustrate the application of the third annotation:
(1) Write the. java file first
(2) Execute the following dos command on the command line:
javadoc *. java//Generate an HTML document from the corresponding Java source code and its explanatory statements
//javadoc tag: It begins with @ and is a special tag for javadoc.
(3) The doc folder will be generated under the current directory, which contains 1 series of. html files
Attach the code:
<span style="font-size:18px;">*/
/**javadoc Contents of comments
*/
public class Hello{
/** Comments on properties */
public String name;
/** This is main Method , Is the entrance to the program
*@param args User input parameters
*/
public static void main(String[] args){
System.out.println("Hello World!");
f1();
}
/** This is the first 1 Methods , Its function is ...*/
public static void f1(){
System.out.println("f1() ! ");
}
}</span>
<span style="font-size:18px;">import java.io.IOException;
/**javadoc Annotation content
*@since 1.0
*@version 1.1
*@author Blue Jey
*<br> Link to another 1 Documents {@link Hello}, That's all
*see Hello
*/
public class HelloWorld{
/** Non public , protected Property does not generate comments on the */
public String name;
/** This is main Method, which is the entry point of the program
*@param args The parameter entered by the user is an array
*@throws IOException main Method io Anomaly
*/
public static void main(String args[]) throws IOException{
System.out.println("hello World!");
f1();
f2(1);
}
/** This is the first 1 Method, its function is ....
*@deprecated From version 1.2 At first, this method is no longer recommended
*/
public static void f1(){
System.out.println("fl()!");
}
/** This is the first 2 Method, its function is ....
*@return Returns whether or not OK
*@param i Input parameters i
*@see Hello
*@throws IOException io Anomaly
*/
public static String f2(int i)throws IOException{
System.out.println("f1()!");
return "OK";
}
} </span>
Note:
If the @ version, @ author tags are available in the source file, add-version-author when executing the javadoc command
javadoc -version -author -d doc *.java
(Where-version is used to extract version information in the source file-author is used to extract author information in the source file)