Javadoc注释文档

• Javadoc 是用于提取文档注释的工具，是JDK安装的一部分。
• Javadoc 会将注释信息和毗邻的类名或方法名同时抽取出来，生成一个很好的程序文档。
• Javadoc输出的是一个HTML文件，可以用WEB浏览器查看。

语法:

    所有命令必须以“/**”开头，以“*/”结尾。独立文档标签 以“@”开头，且必须置于注释行的最前面；行内文档标签 也是以“@”开头，可置于任何位置。

---

 

嵌入式HTML：

可以

/**
* You can <em>even</em> insert a list:
* <ol>
*<li> one </li>
*<li> two </li>
*</ol>
*
*/

输出的文档就会按照HTML标准输出。

---

 

标签示例：

• @see ： 引用其他类； 允许用户引用其他类的文档，Javadoc会在HTML文件中链接到其他文档

@see classname
@see fully-qualified-classname#method-name

• {@docRoot}： 产生到文档根目录的相对路径，用于文芳树页面的显示超链接。
• {@inheritDoc}： 从当前类的最直接基类中继承相关文档到当前的文档注释中。
• @version：版本说明
• @author
• @since：说明程序代码最早使用的版本。
• @param：@param paragram-name description；该标签用于方法文档中，paragram-name是方法参数列表中的标识符，description可延续数行的文本。
• @return：返回值信息
• @throws：抛出的异常
• @Deprecated：用于指出一些旧特性已有新的特性取代，建议用户不要再使用旧特性，因为在不久将来可能会被删除。

---

 

Eclipse文档注释生成方法： 

1.项目-->右键菜单Export-->Java下Javadoc-->next：
<1>javadoc command:就是要调用的javadoc.exe，不用修改，eclipse会找到的；
<2>use standard doclet:就是要生成到的目录，自定义一个文件夹作为存放目录[不然一大堆]；
<3>默认即可next-->再next-->
<4>【注意注意】此时如果项目采用的是UTF-8编码，Extra Javadoc options下需要输入设定参数：-encoding utf-8 -charset utf-8否则生成的网页中文注释都是乱码。
<5>最后Finish完成。
在工程的doc 目录中，就有Javadoc 文档了。

---

文档注释快捷键   

eclipse下，当鼠标处于类，方法定义行时，按Alt+Shift+J，快速添加文档注释。

设置默认格式：file > export > javadoc >

 

 

 

 

 

 

 详见<Thinking in java> P32 : 2.8 注释与嵌入式文档