撰写 Javadoc 时的注意事项

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

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

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

Copyright ＠ 2007-2012 敏韬网(敏而好学，文韬武略--MinTao.Net)（学习笔记） Inc All Rights Reserved.
闵涛 E_mail:admin@mintao.net(欢迎提供学习资源)

鄂公网安备 42011102001154号

站长：MinTao ICP备案号：鄂ICP备11006601号-18