java 生成 appid 工具类 javadoc生成api文档

转载

mob64ca140f67e3 2024-06-23 09:32:55

文章标签 java 生成 appid 工具类 java JAVA JavaDoc API 文章分类 Java 后端开发

1.1 JavaDoc概述

JavaDoc是Java自带的一种工具，其可以从程序源代码中抽取类、方法、属性等注释形成一个和源代码配套的API帮助文档。也就是说，只要在编写程序时以一套特定的标签作注释，在程序编写完成后，通过Javadoc就可以同时形成程序的开发文档了。

Java中有三种注释方法：//单行注释、/多行注释/和/文档注释/，其中第三种专为JavaDoc设计，可以被JDK内置的JavaDoc工具支持和处理。我们可以通过Eclipse来实现Java文件的API文档生成。

1.2 文档注释的格式

Javadoc生成的文档是HTML格式，而这些HTML格式的标识符并不是javadoc添加的，而是我们在写注释的时候写上去的。使用文档注释时，我们应该合理的使用块标记来添加注释信息，常用的块标记包括：

@author 标明开发该类模块的作者
@version 标明该类模块的版本
@param 对方法中某参数的说明
@return 对方法返回值的说明
@exception 对方法可能抛出的异常进行说明

/**
 * 通过javadoc.exe来生成API文档（了解）
 * 1.注释的分类？？？
 *   a)单行注释
 *   b)多行注释
 *   c)文档注释
 * 2.注释的使用？？？
 *   单行注释用于对代码块或方法体中的某行代码做解释说明，文档注释是用于给类、方法（成员方法、静态方法和构造方法）、成员变量、静态变量、
 *   构造代码块和静态代码块做解释说明，而多行注释在实际开发中很少使用。
 * 3.文档注释的概述？？？
 *   使用文档注释的时候，我们需要合理的配合“块标记”来使用，常见的块标记如下：
 *      @version 版本号  --> 说明当前类在哪个版本中开发或在哪个版本中有修改
 *      @author 作者名   --> 说明当前类是哪个程序员开发的。
 *      @param 形参名    --> 对方法的形参做解释说明
 *      @return         --> 对方法的返回值做解释说明
 * 4.生成项目的API文档？？？
 *   IDEA默认集成了javadoc.exe这个可执行程序，因此我们通过IDEA就能够直接生成项目的API文档
 */

【示例】使用块标记实现文档注释案例

/**
 * 老虎类
 * @version 1.0.0
 * @author HHH
 */
public class Tiger {
    /**
     * 姓名
     */
    private String name;

    /**
     * 年龄
     */
    private int age;

    /**
     * 教室
     */
    public static String classRoom;

    /**
     * 无参构造方法
     */
    public Tiger() { }

    /**
     * 有参构造方法（专门给name和age做指定初始化的操作）
     * @param name 赋值的姓名
     * @param age 赋值的年龄
     */
    public Tiger(String name, int age) {
        // 给name成员变量赋值
        this.name = name;
        // 给age成员变量赋值
        this.age = age;
    }

    /**
     * 秀一下即可
     */
    public void show() {
        System.out.println("show ...");
    }

    /**
     * 返回对象的所有成员变量值
     * @return 把对象的成员变量拼接成字符并返回
     */
    @Override
    public String toString() {
        return "Tiger{" +
                "name='" + name + '\'' +
                ", age=" + age +
                '}';
    }
}