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

版权声明:本文为博主原创文章,未经博主允许不得转载。 https://blog.csdn.net/skylake_/article/details/65631591

1、什么是java文档注释

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

2、文档注释的作用

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

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

官方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

效果演示

控制台中生成API文档
演示1
演示2

参数介绍

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中继续设置一些选项,如文档的标题等)

效果演示

演示3
演示4

5、总结

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

展开阅读全文

没有更多推荐了,返回首页