JAVA文档注释----javadoc使用简介

1、什么是java文档注释

java语言除了提供基本的代码注释以外，还提供了一种功能更加强大的注释形式：文档注释。如果编写java源代码时添加了合适的文档注释，然后通过JDK提供的javadoc工具可以直接将源代码里的文档注释提取成一份系统的API文档。

2、文档注释的作用

当开发一个大型软件时，需要定义成千上万个类，而且需要很多人参与开发。每个人都会开发一些类，并在类里定义一些方法和域提供给其他人使用，但其他人怎么知道如何使用这些类和方法呢？这时就需要提供一份说明文档，用于说明每个类、每个方法的用途。当其他人使用一个类或者一个方法时，他无需关心这个类或这个方法的具体实现，他只要知道这个类或这个方法的功能即可，然后使用这个类或方法来实现具体的目的，也就是通过调用应用程序接口（API）来编程。API文档就是用来说明这些应用程序接口的文档。对于java语言而言，API文档通常详细的说明了每个类、每个方法的功能及用法。

3、官方API说明文档效果展示

4、生成自己的API文档

4.1 使用javadoc命令生成文档

我在本地磁盘H:\javaDoc下分别建立javaCode1.java、javaCode2.java，并写入相应的内容。

package skylake;
public class javaCode1{

    String Sentence;
    public static void main(String[] args){

        javaCode1 jd1 = new javaCode1("I Love the world!");


    }
    /**
     *
     *  @param 参数str是一句你想要大声告诉世界的话.
     */
    javaCode1(String str){

        System.out.println("这是一句话 :"+str);
        Sentence = str;

    }
    /**
     *
     *  @return 返回一串字符串 
     */
    public String getSentence(){

        return Sentence;

    }

}

package skylake;
public class javaCode2{

    String Sentence;
    int age;
    public static void main(String[] args){

        javaCode1 jd1 = new javaCode1("I Love the world!");


    }
    /**
     *
     *  @param 参数str是一句想要大声告诉世界的话.
     */
    javaCode2(String str){

        System.out.println("这是一句话 :"+str);
        Sentence = str;

    }
    /**
     *
     *  @return 返回一串字符串 
     */
    public String getSentence(){

        return Sentence;

    }

}

在控制台中输入一下命令：

javadoc -d apidoc *.java

效果演示

参数介绍

javadoc命令支持通配符，例如使用*.java来代表当前路径下的所有java源文件，javadoc常用的选项有如下几个：

-d : 该选项指定一个路径，用于将生成的API文档放到指定的目录下
-windowtitle : 该选项指定一个字符串，用于设置API文档的浏览器窗口标题
-doctitle: 该选项指定一个HTML格式的文本，用于指定概述页面的标题（只有对处于多个包下的源文件来生成API文档时，才有概述页面）
-header: 该选项指定一个HTML格式的文本，包含每个页面的页眉。

常用的javadoc标记

如果我们希望javadoc工具生成更详细的文档信息，例如方法参数、方法返回值等生成详细的说明信息，则可以利用javadoc标记。常用的javadoc标记如下：

@author：指定java程序的作者
@version：指定源文件的版本
@deprecated：不推荐使用的方法
@param：方法参数说明信息
@return：方法返回值说明信息
@see：“参见”，用于指定交叉参考的内容
@exception：抛出异常的类型
@throws ：抛出的异常，和exception同义

4.2 在Eclipse中生成API文档

在eclipse中选择Project–>Generate Javadoc–>选择你想要生成doc的项目工程和文档保存的路径，设置结束后，点击Finish（也可以在next中继续设置一些选项，如文档的标题等）

效果演示

5、总结

这两种方法都可以很快速的帮助我们生成API文档，不过使用命令的时候，经常会遇到编码方面的错误。
eclipse已经帮助我们完成了大量的工作，可以很方便的促进我们的开发。关于API文档这一块儿，如果想要写出高质量的文档，还是应该去参考官方的API文档格式。