简介
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隐去了: