撰写Javadoc需要注意什么？

撰写Javadoc需要注意什么？

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

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

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

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

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

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