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

最新推荐文章于 2021-03-20 13:52:03 发布
风中飘摇我亦妖娆
最新推荐文章于 2021-03-20 13:52:03 发布
阅读量355
点赞数
分类专栏： Intellij IDEA
Intellij IDEA 专栏收录该内容
32 篇文章 0 订阅
订阅专栏
 
 
  
  如果要想使一个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
來源：简书
著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。