编程语言

img casularm

撰写 Javadoc 时的注意事项

发表于2004/10/30 12:35:00  1523人阅读

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

        Javadoc 注解的放置位置:
        1、类或接口:置于 import 语句之后,类或接口的声明之前。
        2、方法、成员变量、构造函数:置于标记式(method signature)之前。
        
        在撰写注解内容时,尽量让第一个句子成为此项目的摘要(以简洁的文字清楚描述此项目的用途)。Javadoc工具程序会将这份摘要复制到类、接口或是成员变量的摘要列表。
       
        对类的行为编制文档远远不只是对每个方法做什么给出一行描述。有效的 Javadoc 应该包括对下列内容的描述:

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

阅读全文
0 0

相关文章推荐

img
取 消
img