用JavaDoc生成API帮助文档

简介

JavaDoc工具是jdk自带的，例如：

JavaDoc解析源代码中的声明和javadoc注释信息，生成HTML形式的API帮助文档。默认包含公开和保护类、嵌套类（但不包含匿名内部类）、接口、构造函数、方法和成员变量。
javadoc注释信息要能被JavaDoc识别，必须紧挨着下面列出的声明并且放在声明的上面：模块、包、类、接口、构造函数、方法、枚举成员、类的字段。
放在方法内部的javadoc注释信息会被JavaDoc忽略。
每个声明只有一个javadoc注释被识别。
注意源代码中javadoc注释格式：

package com.thb;

/**
 * 这是javadoc注释
 * 这是抽象类A
 * @author Administrator
 *
 */
public abstract sealed class A permits B {

	/**
	 * 这是javadoc注释
	 * 这是一个抽象方法
	 */
	public abstract void method();
	
	// 这个不是javadoc注释
	public abstract void method2();
	
	/*
	 * 这个不是javadoc注释
	 */
	public abstract void method3();
	
}

JavaDoc帮助信息

官网资料

JavaDoc命令信息：https://docs.oracle.com/en/java/javase/19/docs/specs/man/javadoc.html
JavaDoc识别的java文档注释规范：https://docs.oracle.com/en/java/javase/19/docs/specs/javadoc/doc-comment-spec.html

在命令行下查看JavaDoc帮助信息

执行javadoc -help命令，可以查看javadoc的帮助信息，截取了部分输出示意如下：

命令行格式

javadoc [options] [packagenames] [sourcefiles] [@files]

• options：声明命令行的选项，多个选项之间用空格隔开。
• packagenames：指明要生成帮助文档的具体包名，多个包名之间用空格隔开，例如com.thb com.thb.client。如果还要包含子包，可以使用-subpackage选项来递归遍历指定的包及其子包。
• sourcefiles：指明具体的源文件名，多个文件名之间用空格隔开，例如A.java B.java。JavaDoc默认在当前路径下搜索指定的源文件名，当然，可以指定源文件的全路径名，里边可以包含通配符；也可以用当前路径的相对路径，例如：D:\temp\eclipse-workspace\java_work\java_test4\src\com\thb\A.java，或者D:\temp\eclipse-workspace\java_work\java_test4\src\com\thb*.java
• @files：指明一个文件，文件中包含命令行的选项、包名、源文件名，顺序不限。当内容很多时，这种方式比较合适。

使用示例

生成一个指定包中所有源文件的帮助文档

代码结构：

进入到包com.thb的上层目录，然后执行命令javadoc -d D:\temp\javadocoutput com.thb就会生成该包下面三个类的帮助信息。命令中的-d D:\temp\javadocoutput是指明输出帮助文档的路径：

输出内容展示：

生成指定包及其下面子包中源文件的帮助文档

代码结构：

执行命令（注意加了-subpackages选项）：

输出内容展示：

指明源文件名生成帮助文档

执行命令：

输出内容展示：

用源文件名通配符生成多个源文件的帮助文档

执行命令：

输出内容展示：

用-sourcepath选项指明源文件的搜索地址

执行命令：

输出内容展示：

包访问控制的类默认不会在生成的API帮助文档中体现

例如，下面的示例代码，类A的声明中用关键字permits指明了只允许类B继承类A，而类B的声明没有访问控制修饰符（也就是包访问控制修饰符）：

package com.thb;

/**
 * 这是javadoc注释
 * 这是抽象类A
 * @author Administrator
 *
 */
public abstract sealed class A permits B {

	/**
	 * 这是javadoc注释
	 * 这是一个抽象方法
	 */
	public abstract void method();	
}


package com.thb;

/**
 * 这是类B
 * @author Administrator
 *
 */
final class B extends A {
	
	/**
	 * 覆盖了类A中的抽象方法
	 */
	public void method() {
		
	}
}

用JavaDoc生成帮助文档：

打开生成的帮助文档：

点击类A进去查看详情，可以看到，在类A的声明中将类B隐去了：