一、文档注释简介
需要编写注释的地方：包 、公有类与接口 、公有的和受保护的构造器及方法、 公有的和受保护的域。
注释应该放置在所描述特性的前面，注释以 /**开始，并以 */ 结束。
每个 /**...*/ 文档注释在标记之后紧跟着自由格式文本。标记由@开始，如@author 或@param。自由格式文本的第一句应该是一个概要性的句子。在自由格式文本中，可以使用 HTML 修饰符，例如，用于强调的 <em>...</em>、 用于着重强调的 <strong>...</strong> 以及包含图像的 <img ...> 等。
没有必要在每一行的开始用星号 *，然而，大部分 IDE 提供了自动添加星号 *, 并且当注释行改变时，自动重新排列这些星号的功能。
二、类注释
类注释必须放在 import 语句之后，类定义之前。
①@author 姓名
这个标记将产生一个"author" (作者）条目。可以使用多个@author 标记，每个@author 标记对应一个作者。
②@version文本
这个标记将产生一个“version”(版本)条目。这里的文本可以是对当前版本的任何描述。
三、方法注释
每一个方法注释必须放在所描述的方法之前。除了通用标记之外，还可以使用下面的标记：
①@param 变量描述
这个标记将对当前方法的“param”(参数)部分添加一个条目。这个描述可以占据多行，并可以使用 HTML 标记。一个方法的所有@param 标记必须放在一起。
② @return 描述
这个标记将对当前方法添加“return”(返回)部分。这个描述可以跨越多行，并可以使用HTML标记。
③@throws 类描述
这个标记将添加一个注释，用于表示这个方法有可能抛出异常。
四、域注释
只需要对公有域（通常指的是静态常量）建立文档。
五、通用注释
下面的标记可以用于所有的文档注释中
⒈@since 文本
这个标记将产生一个“since”(始于)条目。这里的 text 可以是对引人特性的版本描述。例如，@since version 1.7.1。
⒉@deprecated文本
这个标记将对类、方法或变量添加一个“不再使用”的注释。文本中给出了取代的建议。
例如，@deprecated Use <code> setVIsible(true)</code> instead
通过@see和@link标记，可以使用超链接，链接到 javadoc 文档的相关部分或外部文档。
⒊@see 引用
这个标记将在“ see also” 部分增加一个超级链接。
可以为一个特性添加多个@see标记，但必须将它们放在一起。 这里的引用可以选择下列情形之一：
①只要提供类、方法或变量的名字，javadoc 就在文档中插入一个超链接。
例如，@see com.corejava.Employee#raiseSalary(double)建立一个链接到 com.corejava.Employee类的 raiseSalary(double)方法的超链接。可以省略包名，甚至把包名和类名都省去，此时，链接将定位于当前包或当前类。
需要注意，一定要使用井号（#)，而不要使用句号（.）分隔类名与方法名，或类名与变量名。
②如果@see 标记后面有一个'<'字符，就需要指定一个超链接。可以超链接到任何URL。
例如： @see <a href="www.horstmann.com/corejava.html">The Core Java home page</a>
③如果@see 标记后面有一个双引号（"）字符，文本就会显示在 “ see also” 部分。
例如， @see "Core Java 2 volume 2"
⒋@link的特性描述规则与@see标记规则一样。
六、包与概述注释
可以直接将类、方法和变量的注释放置在 Java 源文件中，只要用 /** . . . */ 文档注释界定就可以了。但是， 要想产生包注释，就需要在每一个包目录中添加一个单独的文件。可以有如下两个选择：
1) 提供一个以 package.html 命名的 HTML 文件。在标记 <body>...</body> 之间的所有文本都会被抽取出来。
2) 提供一个以 package-info.java命名的 Java 文件。这个文件必须包含一个初始的以 /** 和 */ 界定的Javadoc 注释，跟随在一个包语句之后。它不应该包含更多的代码或注释。 还可以为所有的源文件提供一个概述性的注释。这个注释将被放置在一个名为 overview.html 的文件中，这个文件位于包含所有源文件的父目录中。标记 <body>...</body> 之间的所有文本将被抽取出来。当用户从导航栏中选择“Overview” 时，就会显示出这些注释内容。
4958
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
