做炒作的网站,app制作费用多少钱,企业门户网站的意义,杭州设计企业网站高端公司文章目录 一、JavaDoc 使用说明1.1 什么是 JavaDoc1.2 文档注释结构1.3 常见的 Javadoc 标签 二、文档最佳实践2.1 注释原则2.2 实际案例 参考资料 一、JavaDoc 使用说明
1.1 什么是 JavaDoc
JavaDoc 是一款能根据源代码中的文档注释来产生 HTML 格式的 API 文档的工具。 Jav… 文章目录 一、JavaDoc 使用说明1.1 什么是 JavaDoc1.2 文档注释结构1.3 常见的 Javadoc 标签 二、文档最佳实践2.1 注释原则2.2 实际案例 参考资料 一、JavaDoc 使用说明
1.1 什么是 JavaDoc
JavaDoc 是一款能根据源代码中的文档注释来产生 HTML 格式的 API 文档的工具。 JavaDoc 相关规则如下
文档注释以 /** 开头、以 */ 结尾并且每行要以星号开头。文档注释覆盖范围包括类、接口、方法、构造器、成员字段如果写在其他位置比如函数内部被视为无效的文档注释。文档注释支持 HTML 语法和 辅助标签。
1.2 文档注释结构
在类/方法上的文档标注一般分为三段顺序如下
第一段概要描述通常用一句话简要描述该类的作用以英文句号结束这句话会被提取并放到索引目录中第二段详细描述通常用一段话或者多段话详细描述该类的作用每段话都以英文句号结束详细描述中可以使用 html 标签如ppreali等标签第三段文档标记通常用于标注作者、创建时间、参阅类等信息描述部分和文档标记之间必须空一行
1.3 常见的 Javadoc 标签 具体细节查看 如何生成一套标准的 Java API 文档 (qq.com) JavaDoc 注释不仅包含文本描述还可以包含特定的标签用于生成结构化的文档。以下是一些常见的 JavaDoc 标签。
标签用途示例注意事项author指明类或接口的作者或组织可以添加邮箱author John Doe有多少个作者就用多少个该标签version指明类或接口的版本version 1.0param描述方法的参数param a the first integerbrparam b the second integerparam 的参数名之后空两格写明各参数的 null 行为return描述方法的返回值return the sum of a and b写明返回值的 null 行为throws描述方法可能抛出的异常throws ArithmeticException if b is zero用 if - 句来描述throwsexception描述方法可能抛出的异常exception ArithmeticException if b is zerosee提供相关的参考信息see java.lang.String必须放在某一行中的最开始since指明自哪个版本开始引入该功能since 1.5deprecated指明该方法或类已经过时deprecated Use {link #newMethod()} instead.{code}用于在文档中插入代码片段{code String result toUpperCase(example);}{link}创建指向其他类或方法的链接see {link java.lang.String}可以放在某一行中的任意位置{inheritDoc}从父类或接口继承文档注释inheritDocserial描述序列化属性serialserialField描述序列化字段serialFieldserialData描述 writeObject 方法的序列化数据serialData
二、文档最佳实践
2.1 注释原则 具体细节查看 Javadoc 最佳实践 | Coding Husky (ericfu.me) 首句中不要使用 link 英文注释推荐使用使用第三人称来描述。 比如 “Gets the foo”避免 “Get the foo” 段落标记使用 p 不用加 /p 闭合它 用 “this” 指代类的对象。当你想描述这个类的一个实例对象的时候用 “this” 来指代它比如 “Returns a copy of this foo with the bar value updated” 用 if - 句来描述 throws。比如 “throws IllegalArgumentException if the file could not be found”。 写明各参数和返回值的 null 行为。一个方法是否接受 null、会不会返回 null 对于其他开发者是十分重要的信息。除非是原始类型param 和 return 都应该注明它是否接受或返回 null。以下标准若适用请务必遵循 “not nul” 表明不接受 null若输入 nul 可能导致异常例如 NullPointerException“may be null” 表明可以传入 null 参数“null treated as xxx”表明 nu 值等价于某个值null returns xxx”表明如果输入 null 则一定会返回某个值
2.2 实际案例
/*** This class represents a simple calculator.* p* This calculator supports basic arithmetic operations such as addition,* subtraction, multiplication, and division.* /p* * author John Doe* version 1.0* since 1.0*/
public class Calculator {/*** Adds two integers.* * param a the first integer,not null* param b the second integer, not null* return the sum of a and b*/public int add(int a, int b) {return a b;}
}参考资料
如何生成一套标准的 Java API 文档 (qq.com)
Javadoc Tool Home Page (oracle.com)
How to Write Doc Comments for the Javadoc Tool (oracle.com)
JavaDoc Documentation Comment Specification for the Standard Doclet (JDK 22) (oracle.com)
Javadoc 最佳实践 | Coding Husky (ericfu.me)
