Java文档注释

Posted 2021-11-29 chy18883701161

　　文档注释主要用于生成API文档，而API文档主要用于说明类、成员变量、方法的功能，所以文档注释只放在类、内部类、接口、成员变量、方法之前，且javadoc只处理这些地方的文档注释，而忽略其它地方的文档注释。

　　API文档相当于产品说明书，而说明书只需要介绍那些暴露的、供用户使用的部分，所以javadoc默认只提取public、protected修饰的部分。如果要提取private修饰的部分，需用 -private 指定。

形式：
/**
文档注释
*/

文档注释可以自己随意写，也可以使用javadoc标记。

常用的javadoc标记：
@author 指定作者(开发者)
@version 指定源文件版本
@deprecated 不推荐使用的方法
@param 方法的参数的说明信息
@return 方法的返回值的说明信息
@see "参见"，指定交叉参考的内容
@exception 抛出的异常类型
@throws 同上

javadoc标记的使用位置是有限制的：
类、接口之前可用@see、@deprecated、@author、@version；
方法之前可用@see、@deprecated、@param、@return、@throws、@exception；

 

示例：

 1 package my_package;
 2 
 3 /**
 4  * Description:
 5  * 网站：<a href="www.jollyaini.com">jolly爱你天才</a><br>
 6  * Copyright (C)，2010-2019，陈洪勇<br>
 7  * This program id protected by copyright laws.<br>
 8  * Program Name:001 文档注释<br>
 9  * Date:2019-05-01<br>
10  * @author 陈洪勇 [email protected]<br>
11  * @version 1.0
12  */
13 public class Name {
14     private String name;
15 
16     /**
17      * 构造函数，初始化name
18      * @param  name 要初始化的name的值
19      */
20     public Name(String name){
21         this.name=name;
22     }
23 
24     /**
25      * 获取name的值
26      * @return 返回name的值
27      */
28     public String getName(){
29         return this.name;
30     }
31 
32     /**
33      * 设置name的值
34      * @param name 要设置的name的值
35      */
36     public void setName(String name){
37         this.name=name;
38     }
39 
40 
41 
42 }
43  

 

 使用IDEA生成API文档：

Tools -> Generate JavaDoc -> 勾选所需选项、设置输出目录、设置参数

 

Locale:zh_CN     指定国家、语言代码，这个参数可缺省

Other command line arguments：-encoding UTF-8 -charset UTF-8     设置命令行参数 

第一个参数表示源文件编码格式为utf-8

第二个参数指定生成的API文档的编码格式为utf-8

主要是为了防止中文乱码

 

点击ok即可。生成的API文档的入口文件为index.html。