Java可执行命令详解之javadoc
- 1️⃣ 概念
- 2️⃣ 优势和缺点
- 3️⃣ 使用
- 3.1 语法格式
- 3.1.1 可选参数：-d < directory>
- 3.1.2 可选参数：-sourcepath < pathlist>
- 3.1.3 可选参数：-classpath < pathlist>
- 3.1.4 可选参数：-link < url>
- 3.1.5 可选参数：-version
- 4️⃣ 应用场景
- 5️⃣ 注意事项
- 🌾 总结
1️⃣ 概念
javadoc是Java的一个可执行命令程序，它旨在为Java源代码生成API文档。它由Sun Microsystems（现为Oracle Corporation）于1995年引入，是Java开发工具包（JDK）的一部分。
javadoc是通过分析源代码中的注释来生成API文档的工具。在编写Java代码时，开发人员可以使用特殊的注释标签来描述类、方法和字段等元素的用途和功能。javadoc会解析这些注释并生成结构化的文档，以便其他开发人员可以更好地理解和使用编写的代码。
javadoc的主要作用是它提供了一个统一的格式来记录代码的设计、用法和约定，并且可以被开发团队中的其他成员使用和参考。这样可以促进代码的可读性、可维护性和重用性。
javadoc的实现原理是通过Java编译器的API（javax.tools）和反射机制来解析源代码中的注释，并生成相应的HTML文档。它可以读取Java源文件或已编译的类文件，并提取注释信息，根据预定义的模板和样式渲染成文档。
2️⃣ 优势和缺点
-
优点：
生成规范化的API文档，方便协作和参考；自动更新文档，避免手动维护文档的繁琐；方便集成到构建系统中，实现自动构建。 -
缺点：
生成的文档可能过于冗长或不够详细；对注释的完整性和准确性有一定依赖；生成的文档有时难以满足特定需求，需要手动修改或使用其他工具补充。
3️⃣ 使用
3.1 语法格式
javadoc 通过源代码和特定格式的注释，生成 API 文档。可以指定要包含在文档中的包名和源文件，以及其他选项。
使用javadoc命令行工具的基本语法格式如下：
javadoc [options] [packagenames] [sourcefiles] [@files]
javadoc是 Java 开发工具包（JDK）中的一个工具，用于从 Java 源代码文件中生成 API 文档；[options]是可选的命令行选项参数，可以用来配置 Javadoc 工具的行为和输出结果；[packagenames]是要处理的源代码包的名称的列表。可以指定一个或多个包名，Javadoc 会根据这些包名查找并处理相应的源代码文件；[sourcefiles]是要处理的源代码文件列表。与包名类似，可以指定一个或多个源代码文件，Javadoc 将处理这些文件并生成文档；[@files]是一个以@符号开头的文件列表。这些文件中包含其他选项和源文件/包名的列表。使用@文件可以简化命令行参数的传递和管理。
综上所述，javadoc 命令用于生成基于注释的API文档。通过命令的不同部分，可以配置选项、指定要处理的源代码包或文件，并使用 @ 文件来引用其他参数文件。命令的具体使用会根据您的需求和项目结构而有所变化。
汇总全部的可选参数如下表：
| 参数 | 作用说明 |
|---|---|
-overview <file> | 从 HTML 文件读取概览文档 |
-public | 仅显示 public 类和成员 |
-protected | 显示 protected/public 类和成员 (默认值) |
-package | 显示 package/protected/public 类和成员 |
-private | 显示所有类和成员 |
-d <directory> | 输出文件的目标目录 |
-sourcepath <pathlist> | 指定查找源文件的位置 |
-classpath <pathlist> | 指定查找用户类文件的位置 |
-doclet <class> | 通过替代 doclet 生成输出 |
-docletpath <path> | 指定查找 doclet 类文件的位置 |
-encoding <name> | 源文件编码名称 |
-locale <name> | 要使用的区域设置, 例如 en_US 或 en_US_WIN |
-windowtitle <text> | 文档的浏览器窗口标题 |
-header <html-code> | 包含每个页面的页眉文本 |
-footer <html-code> | 包含每个页面的页脚文本 |
-top <html-code> | 包含每个页面的顶部文本 |
-bottom <html-code> | 包含每个页面的底部文本 |
-link <url> | 创建指向位于 <url> 的 javadoc 输出的链接 |
-linkoffline <url> <url2> | 利用位于 <url2> 的程序包列表链接至位于 <url> 的文档 |
-stylesheetfile <path> | 用于更改生成文档的样式的文件 |
-tag <name>:\<locations>:\<header> | 指定单个参数定制标记 |
-use | 创建类和程序包用法页面 |
-version | 包含 @version 段版本信息 |
-author | 包含 @author 段作者信息 |
-verbose | 以详细模式执行操作，控制台输出有关 Javadoc 正在执行的操作的信息 |
-quiet | 以安静模式执行操作，减少控制台输出 |
可以看到命令所有的可选参数很多，读者可以根据上边表格选择所需参数来执行命令。下面主要介绍几个常用的参数：
-d <directory>：指定生成文档的输出目录；-sourcepath <pathlist>：指定要生成文档的源代码目录的路径；-classpath <pathlist>：指定编译时需要的类路径；-link <url>：添加外部链接到生成的文档中；-version：在生成的文档中包含版本信息。
3.1.1 可选参数：-d < directory>
javadoc -d <directory> [sourcefiles] 这个命令用于指定生成的文档输出目录并指定要处理的源代码文件。以下是该命令使用的示例：
假设要生成 File1.java 和 File2.java 两个文件的文档：
javadoc -d docs File1.java File2.java
在这个示例中，-d 选项后紧跟着 <directory> 参数 <docs>，表示将生成的文档保存在 docs 目录中。然后，[sourcefiles] 是要处理的源文件的列表，即 File1.java 和 File2.java。
完成上述步骤后，在 docs 目录中可找到生成的文档文件，可以通过打开生成的HTML文件来查看和浏览API文档。
3.1.2 可选参数：-sourcepath < pathlist>
javadoc -sourcepath <pathlist> [sourcefiles] 用于指定源代码的路径列表，以及要处理的源文件。以下是该命令使用的示例：
确定要生成文档的源文件列表，并将它们作为参数传递。例如，假设要生成 com/xiaoshan/MyClass.java 文件的文档：
javadoc -sourcepath src/com/xiaoshan MyClass.java
在这个示例中，-sourcepath 选项后紧跟着 <pathlist> 参数。<pathlist> 是源代码的路径列表，它可以包含多个路径，用于查找源文件。然后，[sourcefiles] 是要处理的源文件的列表，即 MyClass.java 。
Javadoc 将根据指定的源代码路径和源代码文件生成相应的文档，默认情况下会将生成的文档放在当前目录中。
完成上述步骤后，将生成相应的API文档。
查看执行命令输出结果：
然后在目录中查看生成的HTML文档文件：
点开MyClass.html文件查看生成的javadoc文档，里边是完整的MyClass类信息：
3.1.3 可选参数：-classpath < pathlist>
javadoc -classpath <pathlist> [sourcefiles] 命令用于指定编译时所需的类路径，以及要处理的源代码文件。以下是该命令使用的示例：
确定要生成文档的源文件列表，并将它们作为参数传递。例如，假设要生成 com/example/Class1.java 和 com/example/Class2.java 两个文件的文档：
javadoc -classpath lib/*:other/dependency.jar com/example/Class1.java com/example/Class2.java
在这个示例中，-classpath 选项后紧跟着 <pathlist> 参数。<pathlist> 是编译时所需的类路径列表，这些类路径可以包含项目的依赖库、JAR文件等。使用冒号 (:) 分隔多个类路径。然后，[sourcefiles] 是要处理的源文件的列表，即 com/example/Class1.java 和 com/example/Class2.java。
Javadoc 将根据指定的类路径和源代码文件生成相应的文档，默认情况下会将生成的文档放在当前目录中。
3.1.4 可选参数：-link < url>
javadoc -link <url> [sourcefiles] 用于将外部链接添加到生成的文档中。以下是该命令使用的示例：
确定要生成文档的源文件列表，并将它们作为参数传递。例如，假设要生成 com/example/Class1.java 和 com/example/Class2.java 两个文件的文档，并添加一个名为 https://example.com/docs 的外部链接：
javadoc -link https://example.com/docs com/example/Class1.java com/example/Class2.java
在这个示例中，-link 选项后紧跟着 <url> 参数，表示要添加的外部链接的URL。然后，[sourcefiles] 是要处理的源文件的列表，即 com/example/Class1.java 和 com/example/Class2.java。
Javadoc 将根据指定的源代码文件和外部链接生成相应的文档，默认情况下会将生成的文档放在当前目录中。
3.1.5 可选参数：-version
javadoc -version [sourcefiles] 用于在生成的文档中包含Java平台的版本信息。以下是该命令使用的示例：
确定要生成文档的源文件列表，并将它们作为参数传递。例如，假设要生成 com/example/Class1.java 文件的文档，并包含Java平台的版本信息：
javadoc -version com/example/Class1.java
在这个示例中，-version 选项表示要在生成的文档中包含Java平台的版本信息。然后，[sourcefiles] 是要处理的源文件的列表，即 com/example/Class1.java 。
Javadoc 将根据指定的源代码文件和版本信息生成相应的文档，默认情况下会将生成的文档放在当前目录中。
4️⃣ 应用场景
javadoc广泛应用于 Java 开发领域，适用于各种规模的项目和团队。主要应用场景包括：
- 为外部开发者或用户文档生成API参考手册；
- 提供内部开发人员参考和学习使用；
- 促进协作和沟通，在团队中共享代码设计和用法；
- 文档规范化，方便后续维护和追溯历史记录。
5️⃣ 注意事项
在使用javadoc时，需要注意以下几点：
- 注释必须遵循
javadoc的注释格式要求； - 注释要准确、完整地描述元素，以生成准确的API文档；
- 注释应该包含足够的示例代码和使用说明，以供他人参考。
🌾 总结
javadoc是Java开发中非常有用的工具，能够自动化生成结构化的API文档。它提供了一种统一的方式来记录和共享代码的设计和用法，促进协作和沟通。尽管有一些缺点，但在大多数Java项目中都可以发现javadoc的身影，为代码的可读性和可维护性做出了重要贡献。
