Of Stack

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)

Related articles: