• 如何使用Javadoc为API应用生成文档说明?
  • 发布于 1周前
  • 39 热度
    0 评论
  • 耀国
  • 0 粉丝 37 篇博客
  •   
一、简介
在开发项目的时候,我们可能时不时需要查阅官方 JDK API 文档,以便于更加清晰的了解某个类方法的用途以及正确的使用姿势,比如关于 HashMap 类的介绍。

打开 JDK 源码,你会看到代码上有大量的文档注释,包括包的描述、类的描述、方法描述以及类属性的描述说明等等,同时你还会惊奇的发现,源码上的注释与 JDK API 文档中的描述如出一辙,以 HashMap 为例,类注释描述如下!

实际上,JDK API 文档是根据 Javadoc 工具生成的!
那什么是 Javadoc 呢?
官方回答: Javadoc is a tool for generating API documentation in HTML format from doc comments in source code.
翻译过来的意思是:Javadoc 是一款能根据源代码中的文档注释来产生 HTML 格式的 API 文档的工具。

简单的说就是,只要你在 java 源码中按照标准的格式写注释,就可以利用 javadoc 这款工具自动生成配套的 java API 文档。本篇文章的主要内容,就是总结 java 文档注释应该按照什么样的格式来写,只要格式对了,java API 文档就能按照工具来自动生成。

二、文档注释格式总结
Java 文档注释是专门为了用 javadoc 工具自动生成文档而编写的一套注释标准,通过 javadoc 命令可以把文档注释中的内容生成文档,并输出到 HTML 文件中,与一般的注释有所不同,相关的规则如下:
1.所有的 Java 文档注释都以/**开头,*/结尾,而不是/*或//
2.文档注释覆盖范围包括:类、接口、方法、构造器、成员字段,如果写在其他位置,比如函数内部,被视为无效的文档注释
3.每个 Java 文档注释都要和其后对应的类/方法/字段/包保持同样的缩进

4.Java 文档注释的内容,支持采用HTML语法规则书写,同时也支持一些额外的辅助标签


在类/方法上的文档标注一般分为三段,顺序如下:
第一段:概要描述,通常用一句话或者一段话简要描述该类的作用,以英文句号结束,这句话会被提取并放到索引目录中
第二段:详细描述,通常用一段话或者多段话详细描述该类的作用,每段话都以英文句号结束,详细描述中可以使用 html 标签,如<p>,<pre>,<a>,<li>等标签
第三段:文档标记,通常用于标注作者、创建时间、参阅类等信息,描述部分和文档标记之间必须空一行
比如java.util.Arrays类和部分方法,源码 java 文档注释如下!
package java.util;

/**
 * This class contains various methods for manipulating arrays (such as
 * sorting and searching). This class also contains a static factory
 * that allows arrays to be viewed as lists.
 *
 * <p>The documentation for the methods contained in this class includes
 * briefs description of the <i>implementations</i>. Such descriptions should
 * be regarded as <i>implementation notes</i>, rather than parts of the
 * <i>specification</i>. Implementors should feel free to substitute other
 * algorithms, so long as the specification itself is adhered to. (For
 * example, the algorithm used by {@code sort(Object[])} does not have to be
 * a MergeSort, but it does have to be <i>stable</i>.)
 *
 * <p>This class is a member of the
 * <a href="{@docRoot}/../technotes/guides/collections/index.html">
 * Java Collections Framework</a>.
 *
 * @author Josh Bloch
 * @author Neal Gafter
 * @author John Rose
 * @since  1.2
 */
public class Arrays {
 
    /**
     * Sorts the specified array into ascending numerical order.
     *
     * <p>Implementation note: The sorting algorithm is a Dual-Pivot Quicksort
     * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
     * offers O(n log(n)) performance on many data sets that cause other
     * quicksorts to degrade to quadratic performance, and is typically
     * faster than traditional (one-pivot) Quicksort implementations.
     *
     * @param a the array to be sorted
     */
    public static void sort(int[] a) {
        DualPivotQuicksort.sort(a, 0, a.length - 1, null, 0, 0);
    }
}
三、文档标签总结
Javadoc 工具可以识别文档注释中的一些特殊标签,这些标签一般以@开头,后跟一个指定的名字,有的也以{@开头,以}结束,javadoc 可以识别的标签如下!

@author
说明:用于指明作者或者组织,可以附加邮箱或者超链接,如果有多少个作者就用多少个该标签。适用范围:包、 类、接口 案例如下:
/**
 * @author xxxx
 * @author xxx@123.com
 * @author <a href="mailto:xxx@123.com">xxxxx</a>
 */
@since
说明:用于指明最早出现在哪个版本,可填版本号或日期,有时也可表明可运行的JDK版本。适用范围:包、类、接口、方法、成员属性、构造器 案例如下:
/**
 * @since 1.4
 * @since 15 April 2001
 * @since JDK1.5
 */
@version
说明:用于指明当前版本号。适用范围:包、 类、接口 案例如下:
/**
 * @version 1.8.3.4
 */
@code
说明:用于将一些关键字或代码解析成代码样式。适用范围:包、类、接口、方法、成员属性、构造器 案例如下:
/**
 * xxxx,{@code int var = 1;}xxxx
 */
@return
说明:对函数返回值的注释。适用范围:方法 案例如下:
/**
 * @return <code>true</code> 执行成功;<code>false</code> 执行失败.
 */
@param
说明:用于方法的入参名及描述信息。适用范围:构造器、方法 案例如下:
/**
 * @param img the image to be drawn
 */
@value
说明:只能用于对常量进行注释,该标签常用于写在字段上的 Javadoc 注释。适用范围:方法、成员属性 案例如下:
/**
 * Default start value. {@value #START_VALUE}
 */
@throws 和 @exception
说明:用户描述构造函数或方法所会抛出的异常。适用范围:方法、构造器 案例如下:
/**
 * @throws IllegalArgumentException
 *         if {@code fromIndex > toIndex}
 */
@link 、@linkplain 和 @see
说明:用于创建一个超链接到相关代码。适用范围:包、类、接口、方法、成员属性、构造器 注意事项:1、@link 和 @linkplain的区别在于:@link直接将将超链接中的地址当作显示的文本,其格式为 {@link 地址};而 @linkplain可以自行设定显示的文本,其格式为{@link 地址 显示文本},三个字段用空格隔开。2、@link 和 @see的区别在于:@link可以放在某一行中的任意位置;而 @see必须放在某一行中的最开始。

案例如下:
/**
 * xxx {@link java.lang.String#charAt(int)}
 * xxx {@link #sort(Object[])}
 * xxx {@linkplain Comparable natural ordering}
 * @see #deepHashCode(Object[])
 */
@inheritDoc
说明:用于继承父类的 javadoc 注释,父类的文档注释会被拷贝到子类。适用范围:方法 案例如下:
/**
 * {@inheritDoc}
 * <p>
 * The speed of tiger will be returned.
 * 
 * @return the speed of tiger 
 */
@deprecated
说明:告诉用户该 API 已过时,并且已被哪些新的 API 取代了。用@see或 @link指向新的API。该旧的 API 之所以不删掉,通常是为了兼容性考虑。。适用范围:包、类、接口、方法、成员属性、构造器 案例如下:
/**
* @deprecated As of JDK 1.1, replaced by 
* {@link #setBounds(int, int, int, int)}
*/
@serial
说明:说明一个序列化属性。适用范围:方法、成员属性 案例如下:
/**
 * @serial description
 */
@serialData
说明:用于说明通过 writeObject() 和 writeExternal() 方法写的数据。。适用范围:方法、成员属性 案例如下:
/**
 * @serialData description
 */
@serialField
说明:用于说明一个 ObjectStreamField 组件。适用范围:方法、成员属性 案例如下:
/**
 * @serialField name type description
 */
最后,在使用文档注释时,通常会按照如下顺序进行使用。
@author
@version
@param
@return
@exception / @throws
@see
@since
@serial / @serialField / @serialData

@deprecated


四、java api 文档生成方式
Javadoc 是 Sun 公司提供的一个技术,它从程序源代码中抽取类、方法、成员等注释,然后形成一个和源代码配套的 API 帮助文档。
文档的创建命令如下:
javadoc -d 文档存放目录 -author -version 源文件名.java
这条命令编译一个名为源文件名.java的 java 源文件,并将生成的文档存放在文档存放目录指定的目录下,生成的文档中index.html就是文档的首页。
-author和-version两个选项可选项,使用者可以通过javadoc -help命令查看 javadoc 使用说明。
注意:Javadoc 默认只提取 public、protected 修饰的部分,如果要提取 private 修饰的部分,需要使用 -private。

下面是一个使用说明文档注释的简单实例。
/**
 * 这个类演示了文档注释
 * 堆代码 duidaima.com
 * @author Ayan Amhed
 * @version 1.2
 */
public class SquareNum {
    /**
     * This method returns the square of num.
     * This is a multiline description. You can use
     * as many lines as you like.
     *
     * @param num The value to be squared.
     * @return num squared.
     */
    public double square(double num) {
        return num * num;
    }

    /**
     * This method inputs a number from the user.
     *
     * @return The value input as a double.
     * @throws IOException On input error.
     * @see IOException
     */
    public double getNumber() throws IOException {
        InputStreamReader isr = new InputStreamReader(System.in);
        BufferedReader inData = new BufferedReader(isr);
        String str;
        str = inData.readLine();
        return (new Double(str)).doubleValue();
    }

    /**
     * This method demonstrates square().
     *
     * @param args Unused.
     * @return Nothing.
     * @throws IOException On input error.
     * @see IOException
     */
    public static void main(String args[]) throws IOException {
        SquareNum ob = new SquareNum();
        double val;
        System.out.println("Enter value to be squared: ");
        val = ob.getNumber();
        val = ob.square(val);
        System.out.println("Squared value is " + val);
    }
}
使用 javadoc 工具处理 SquareNum.java 文件,生成 javadoc api 文档,在命令行输入如下命令,即可实现文档的生成!
javadoc SquareNum.java
四、小结
Javadoc 是一款为程序生成 API 文档的工具,只需按照规定的格式编写代码文档注释,即可生成 API 的帮助文档。

本文主要围绕 java 文档标签的使用进行介绍,如果有错误的地方,欢迎网友留言指出!
用户评论