良好习惯,编写自己的JAVADOC

JavaDoc 可以根据我们写的代码,直接生成 api 的帮助文档,我们天天看的 JDK帮助文档就是用 JavaDoc 生成的,各大开源软件里面的 Api文档也都是 Javadoc。

只要写代码的时候注意点,多留点心写下代码的说明,那么自己的项目中也可以生成出漂亮的JavaDoc来。

使用javadoc 命令行,和 eclipse 的工具都可以给快速生成一个项目的API帮助文档。

  1. 包的javadoc:在所在包的下面建立一个package.html文件,进行描述。通常进行简单描述包的功能和一些注意事项。
    如果有必要就在包上加上这个html文件,javadoc工具会自动生成package-summary.html文件。虽然是HTML文件 ,但也不一定要写成HTML,如果喜欢可以直接写文字,但一般还是保留最基本结构,如:

    1
    2
    3
    4
    5
    6
    <h3>com.xdnote</h3>
    <ul>
    <li>com.xdnote包说明一</li>
    <li>com.xdnote包说明二</li>
    </ul>
          com.xdnote注意事项
  2. 类的javadoc
    类的javadoc估计都见得不少了,在eclipsenew一个class或是interface时都会有杂七杂八的注释,或是开源代码每份上面都会有lisene什么的。
    一般工具都会对javadoc自动识别,开发过程中也会有不少帮助,比如
    javadoc
    类的javadoc一般格式

    1
    2
    3
    4
    5
    /**
    * {Description}
    *
    * {Tags}
    */

一般javadoc的编写也需要一定的规范,保证输出的一致性,建议要有题干,有简单直接的说明。对于方法,如果有参数就必须带@param,有返回就必须带@return,有异常就必须带@throws或@exception,常见的tag有

名称 作用 备注
@param 参数描述 仅供类、接口、方法注释时使用。同一个注释块可同时出现多个param描述。
@return 返回描述 仅供方法注释时使用。除void方法外其它所有方法必须有一个return描述。
@throws 异常描述 零到多个。
@exception 异常描述 零到多个。
@author 作者 类和接口注释中必须有。可有零到多个。
@version 版本描述 类和接口注释中必须有。零或一个。
@see 参考描述 可有零到多个。
@since 起始版本 只有一个。
@serial 序列化描述 @serialField@serialData,可有多个
@deprecated 废除标志 最多一个。

Tag还有很多,建议做Java开发的都去理解并写到代码里面,用不了多少工作量,让代码漂亮起来。

推荐一款eclipse插件:checkStyle,一般开发使用这个插件可以保持代码风格差不多,设置好规后会自动在类说明。方法说明的部件生成JavaDoc,使得编写JavaDoc更容易。可以在eclipse里面help菜单中安装插件,地址http://eclipse-cs.sourceforge.net/update。