Javadoc中的Tag说明

Tag的一些惯例

一些Tags的说明

• @author：作者的姓名
• @version：版本号
• @param：对于参数的描述
• @return：对于返回内容的描述
• @exception (和@throws是同义词)：异常类的名称和描述
• @see：表示去查看参考资料
• @since：表示这个变更或特性从什么时候或版本号等（由该标签中声明的内容决定）开始存在的
• @serial：用于表示序列化的字段（include | exclude）
• @deprecated：表示被弃用
• @link：用法{@link package.class#member label}。插入一个带标签的链接，可以指向特定包、类或指定类的成员名称的文档。
• @literal：用法{@literal text}。用来显示那些不用被HTML标记或嵌套javadoc标签解析的文本。

Tags的顺序

按照下面的顺序写tags：

• @author (仅用于类和接口，必须的)
• @version (仅用于类和接口，必须的)
• @param (仅用于方法和构造函数)
• @return (仅用于方法)
• @exception (和@throws是同义词)
• @see
• @since
• @serial (或者@serialField，@serialData)
• @deprecated

对多个相同tags的排序

按照下面的惯例来使用多个相同tags。如果需要，可以用空白行（单*）来隔离这些包含多个相同tags的组。

• 多个@author标签，应该按照发生时间顺序排列，最早的发在最上面。
• 多个@param标签，应该按照参数的声明顺序排列。
• 多个@throws标签（或@exception），应该按照异常名称的字母顺序排列。

必须的Tags

按照惯例，每一个参数都应该有一个@param标签，即使描述很明显。每一个返回不是void的方法都应该有一个@return标签，即使这个标签和方法的描述内容重复。

参考资料

How to Write Doc Comments for the Javadoc Tool