Java文档注释

Posted 2020-08-27

　　文档注释是用于生成API文档，API主要用于说明类、方法、成员变量

•  javadoc工具 处理文档源文件在类、接口、方法、成员变量、构造器和内部类之前的注释，忽略其他地方的文档注释。而且javadoc工具默认只处理以public或protected修饰的类、接口、方法、成员变量、构造器和内部类之前的文档注释。
• 如果开发者希望javadoc工具可以提取private修饰的内容，则可以使用javadoc工具是增加-private选项

 

     javadoc命令的基本用法如下：

  javadoc 选项 Java源文件|包

    java源文件可以支持通配符：

　　如，使用*.java来代表当前路径下所有的java源文件。

    javadoc 的常用选项：

•  -d<directory>: 该选项指定一个路径，用于生成的API文档存放到的指定目录下。
• -windowtitle<text>: 该选项指定一个字符串，用于设置API文档的浏览器窗口标题。 
• -doctitle<html-code>:该选项指定一个HTML格式文本，用于指定概述页面的标题。 只有处于当个包下的源文件来生成API文档时，才有概述页面。
• -header<html-code>:该选项指定一个HTML格式的文本，包含么个页面的页眉。

  

 javadoc -d apidoc -windowtitle 测试 -doctitle 学习 javadoc 工具的测试 API 文档 -header 我的类*Test.java　　　　　　　　　　　　　　　　　　　　　　　　

 

   javadoc标记：

•   @author: 指定Java程序的作者。
•   @version:指定源文件的版本。
•   @deprecated:不推荐使用的方法。
•   @param: 方法的参数说明。
•   @return: 方法的返回值说明信息。
•   @see: "参见“，用于指定交叉参考的内容。
•   @exception:  抛出的异常的类型。
•   @throws: 抛出的异常，和@exception同义。

 

    上面的标记的使用有位置限制的。

    出现在类或者接口文档注释中的有@see、@deprecated、@author、@version等

    可以出现在方法或者构造器文档注释的有@see、@deprecated、@param、@return、@throws、和@exception等

    可以出现在成员变量的文档注释中的有@see和@deprecated等