第44条 为所有导出的API元素编写文档注释

 
 

如果要想使一个API真正可用,就必须为其编写文档。传统意义上的API文档是手动生成的,所以保持文档与代码同步是一件很繁琐的事情。Java环境提供了一种被称为Javadoc的实用工具,从而使这项任务变得很容易。Javadoc利用特格式的文档注释,根据源代码自动产生API文档。

如何使用Javadoc?相关资料:http://blog.csdn.net/nothing0318/article/details/7258523 1.在myeclipse中点击导航栏中的 project->Generate javadoc弹出如下界面,然后勾选需要生成文档的包以及生成文档的位置。

da74efb0892d41c9ad951d974391789b.png

如何添加中文javadoc?相关资料: http://www.cnblogs.com/mq0036/p/3788511.html

2.在dos命令提示符中输入:javadoc -d myhelp -author -version Register.java(也可以编译整个文件夹,javadoc -d myhelp -author -version test) -d 表示生成的目录位置,myhelp表示生成文档所在当前目录下的文件夹名 -author是作者的名字 -version是版本号(这两项非必填项,不写的话不会生成相应的文档注释内容) ps:如果注释中有中文,需要在dos命令中加入-encoding utf-8 -charset utf-8

基础知识: 1./**this is a description*/注释若干行,并写入 javadoc 文档 2.文档注释三部分:

/**
* show 方法的简述.
* <p>show 方法的详细说明第一行<br>
* show 方法的详细说明第二行
* @param b true 表示显示,false 表示隐藏
* @return 没有返回值
*/
public void show(boolean b) {
frame.show(b);
}

第一部分是简述。文档中,对于属性和方法都是先有一个列表,然后才在后面一个一个的详细的说明

第二部分是详细说明部分。该部分对属性或者方法进行详细的说明,在格式上没有什么特殊的要求,可以包含若干个点号。

第三部分是特殊说明部分。这部分包括版本说明、参数说明、返回值说明等。

  • @param b true 表示显示,false 表示隐藏
  • @return 没有返回值

添加文档注释规范:
一、为了正确地编写API文档,必须在每个被导出的类、接口、构造器、方法和域声明之前增加一个文档注释。
二、方法的文档注释应该简洁的描述出它和客户端之间的约定。这个约定应该说明这个方法做了什么,而不是说明它是如何完成这项工作的。文档注释应该列举如下内容:
1.前提条件(precondition) 前提条件是指为了使客户能够调用这个方法,而必须满足的条件;
2.后置条件(postcondition) 所谓后置条件是指在调用成功完成之后,哪些条件必须要满足;
3.副作用(side effect) 副作用是指系统状态中可以观察到的变化,它不是为了获得后置条件而明确要求的变化;
4.类或者方法的线程安全性(thread safety)(详见70条) 当一个类的实例或者静态方法被并发使用时,这个类行为的并发情况。

文档注释示例:

/** 
 * Returns the element at the specified position in this list. 
 * 
 * <p>This method is <i>not</i> guaranteed to run in constant 
 * time. In some implementations it may run in time proportional 
 * to the element position. 
 * 
 * @param index index of element to return; must be 
 *        non-negative and less than the size of this list 
 * @return the element at the specified position in this list 
 * @throws IndexOutOfBoundsException if the index is out of range 
 *         ({@code index < 0 || index >= this.size()}) 
 */  
 E get(int index);

•文档注释必须以/**开头,否则Javadoc无法识别。
•文档注释第一句话作为概要描述。概要描述必须独立地描述目标元素的功能,同一个类或接口中的任意两个成员或构造器,不应该具有相同的概要描述。即使是重载方法也不行。
•每个参数都应该有一个@param标签,标签后面第一个单词为参数名称,接着是对该参数的解释和要求。
•返回类型非void的方法都应该有一个@return标签,描述返回值所表示的内容。
•该方法可能抛出的每一个异常,无论是受检异常还是非受检异常,都要对应一个@throws标签。标签后面第一个单词为异常类型,接着是一句话,应该以if开头,描述该异常将在什么情况下被抛出。@param、@return和@throws都不以句点结束。
• @code标签可用于任何需要展示代码的地方,被该标签包围的内容会以特殊的字体显示,并且不对其中内容做任何HTML解析。
•按惯例,单词“this”用在实例方法的文档注释中时,应该始终是指方法调用所在的对象。
•可以用@literal标签展示包含HTML元字符的句子。它除了不改变显示样式外,其余效果和@code一样。

Java 1.5发行版本中增加的三个特性在文档注释中需要特别小心:泛型、枚举和注解。当为泛型或者方法编写文档时,确保要在文档中说明所有的类型参数。

/**
 * @author zhaiyanming
 * @version 1.0
 * @param <K> the type of keys maintained by the map
 * @param <V> the type of mapped values
 */
public interface Map<K, V> {
    //dosomething
}

当为枚举类型编写文档时,要确保在文档中说明常量,以及类型,还有任何公有的方法。

/**
 * three primary colours
 * @author zhaiyanming
 * @version 1.0
 * return enum
 */
public enum Color {
    /** Red, the color of blood. */
    RED,
    /** Green, the color of grass.  */
    GREEN,
    /** Blue, the color of sea. */
    BLUE;
}

为注解类型编写文档时,要确保在文档中说明所有成员,以及本身类型。对于该类型的概要描述,要使用一个动词短语,说明当程序元素具有这种类型的注解时它表示什么意思。

import java.lang.annotation.ElementType;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Indicates that the annotated method is a test method that
 * must throw the designated exception to succeed.
 * @author zhaiyanming
 * @version 1.0
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ExceptionTest {
    /**The exception that the annotated test method must throw
     * in order to pass. (The test is permitted to throw any
     * subtype of the type described by this class object.) */
    Class<? extends Exception> value();
}

类的导出API有两个容易被人忽略的特征:
1.类是否是线程安全的应该在文档中对它的线程安全级别进行说明。(如70条所述)
2.如果类是可序列化的,就应该在文档中说明它的序列化形式。(如第75条所述)

简而言之,要为API编写文档,文档注释是最好、最有效的途径。对于所有可导出的API元素来说,使用文档注释应该被看作是强制性的。要采用一致的风格来遵循标准的约定。在文档注释内部出现任何HTML标签都是允许的,但是HTML字符必须要经过转义。



作者:真爱也枉然
链接:http://www.jianshu.com/p/4cd633e971fb
來源:简书
著作权归作者所有。商业转载请联系作者获得授权,非商业转载请注明出处。
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

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

抵扣说明:

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

余额充值