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的身影，为代码的可读性和可维护性做出了重要贡献。