Java doc

今天主要简单介绍一下java doc, 所谓高手比拼在细节，写好javadoc 也是Java程序员的必备技能，下面看一些较为规范的写法

javadoc xxx.java 文件即可生成javadoc文档。

注释条件

• 1. 基本注释（必须加）
     (a)类（接口）的注释
     (b)构造函数的注释
     (c)方法的注释
     (d)全局变量的注释
     (e)字段/属性的注释
     备注：简单的代码做简单注释，注释内容不大于10个字即可，另外，持久化对象或VO对象的getter、setter方法不需加注释。具体的注释格式请参考下面举例。
• 2. 特殊必须加注释（必须加）
     (a)典型算法必须有注释。
     (b)在代码不明晰处必须有注释。
     (c)在代码修改处加上修改标识的注释。
     (d)在循环和逻辑分支组成的代码中加注释。
     (e)为他人提供的接口必须加详细注释。
     备注：此类注释格式暂无举例。具体的注释格式自行定义，要求注释内容准确简洁

1、 @author

在类前面使用可以添加多个@author
一般可以写为 @author xxx
但是推荐是写成如下带邮箱的格式：

/**
 * @author <a href="mailto:xxx@xxx.com">ice</a>
 */

2、 {@code }

在JavaDoc 中{@code memberData} 和 <code>memberData</code> ]有什么不同之处呢？

两者大意相同，但是{@code memberData} 有如下两个优点：
1、更易读
2、在 {@code ...} 中的文字会自动转换.

比如, {@code List<String>} 等价与 <code>List<String></code>.

参考网址：
What is the difference between {@code memberData} and <code>memberData</code> in JavaDoc

3、@param

表示方法参数，用在方法上。

    /**
     * 获取总金额
     *
     * @param date 请求参数，表示日期
     * @return 返回指定日期的总金额
     * @see  #String(byte[], int)
     * @see  #String(byte[], int, int, java.lang.String)
     * @see  #String(byte[], int, int, java.nio.charset.Charset)
     * @see  #String(byte[], int, int)
     * @see  #String(byte[], java.lang.String)
     * @see  #String(byte[], java.nio.charset.Charset)
     * @see  #String(byte[])
     */
    public long getTotalMoney(String date) {
       //todo here
    }

4、@return

表示方法的返回值

5、@see

表示参考类、方法

比如jdk中的String类如下

 /*
 * xxxx
 * @author  Lee Boynton
 * @author  Arthur van Hoff
 * @author  Martin Buchholz
 * @author  Ulf Zibis
 * @see     java.lang.Object#toString()
 * @see     java.lang.StringBuffer
 * @see     java.lang.StringBuilder
 * @see     java.nio.charset.Charset
 * @since   JDK1.0
 */

public final class String

6、@exception

对方法可能抛出的异常进行说明

7、@version

对类的说明 ，标明该类模块的版本 ，用的不多