撰写 Javadoc 时的注意事项

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

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

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

  • 0
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 1
    评论
评论 1
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值