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标签，即使这个标签和方法的描述内容重复。
网友评论