撰写Javadoc需要注意什么?

撰写Javadoc需要注意什么?


Javadoc 以 /** 开头,并以 */ 做结尾。每个Javadoc注解都伴随着一个或多个标签,必要时,也可在注解内使用HTML标签。

撰写 Javadoc 注解时,请遵守下列几项原则:
1、将“注解开始符号 /** 缩排,对齐欲注释的程序码。
2、从第二行开始撰写注解内容(第一行为“注解开始符号”),每行注解均以星号 * 作为开头,并于“注解开始符号”的第一个信号对齐。
3、在说明文字与标签列表之间插入一行空白注解。
4、最后一行(不包括注解内容)为“注解结束符号” */

Javadoc 注解的放置位置:
1、类或接口:置于 import 语句之后,类或接口的声明之前。
2、方法、成员变量、构造函数:置于标记式(method signature)之前。

在撰写注解内容时,尽量让第一个句子成为此项目的摘要(以简洁的文字清楚描述此项目的用途)。Javadoc工具程序会将这份摘要复制到类、接口或是成员变量的摘要列表。

对类的行为编制文档远远不只是对每个方法做什么给出一行描述。有效的 Javadoc 应该包括对下列内容的描述:

1、类如何相互关联
2、方法如何影响对象的状态
3、方法如何将出错条件通知它们的调用者以及它们可能通知什么错误
4、类如何处理多线程应用程序中的使用
5、方法的参数作用域及其返回值的范围