生成Javadoc的Java库JAR方法详解

Java库的高质量交付不仅依赖于功能完备的主JAR包，更需严格遵循“三件套”分离发布规范——即独立生成并配套发布`-sources.jar`（源码）、`-javadoc.jar`（HTML文档）与主JAR，三者通过标准命名被IDE（如IntelliJ）自动识别，实现悬停查看文档、快捷跳转源码等无缝开发体验；文章详解了为何Javadoc不能嵌入主JAR（因其本质是静态资源，与字节码无关）、如何用Maven插件一键生成三件套、关键配置要点及常见误区，揭示了专业Java库构建中“运行时精简”与“开发时友好”协同统一的核心实践。

Java 库的 JAR 文件本身不包含 Javadoc（仅含编译后的字节码），文档需单独生成并以 *-javadoc.jar 形式发布；IDE（如 IntelliJ）通过约定命名自动关联，实现悬停提示与源码跳转。

在 Java 生态中，一个专业、可协作的库（Library）不仅需要提供功能完备的 .jar（含 .class 文件），还必须配套提供可被 IDE 识别的 Javadoc 和源码支持——但这三者（主 JAR、Javadoc JAR、Sources JAR）是物理分离、逻辑协同的三个独立构件，而非打包进同一个 JAR 中。

✅ 正确做法：三件套分离发布

标准 Maven/Gradle 构建流程会生成以下三个 JAR 文件（命名遵循约定）：

? 为什么不能把 Javadoc 编译进主 JAR？
因为 Javadoc 是纯注释内容（/** ... */），在 javac 编译过程中不会生成任何字节码，也不会嵌入 .class 文件。它本质是独立的 HTML/JS/CSS 静态资源集，体积可能远超主 JAR —— 强行合并将显著增大部署包，违背“运行时最小化”原则（类似 C/C++ 的 .so/.dll 不含 Doxygen 文档）。

? 示例：使用 Maven 自动生成三件套

在 pom.xml 中添加以下插件配置：

<build>
  <plugins>
    <!-- 生成 Sources JAR -->
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-source-plugin</artifactId>
      <version>3.2.1</version>
      <executions>
        <execution>
          <id>attach-sources</id>
          <goals><goal>jar-no-fork</goal></goals>
        </execution>
      </executions>
    </plugin>

    <!-- 生成 Javadoc JAR -->
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-javadoc-plugin</artifactId>
      <version>3.5.0</version>
      <executions>
        <execution>
          <id>attach-javadocs</id>
          <goals><goal>jar</goal></goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

执行命令打包：

mvn clean package
# 输出目录 target/ 下将包含：
# mylib-1.0.0.jar
# mylib-1.0.0-sources.jar
# mylib-1.0.0-javadoc.jar

? IntelliJ 中的自动识别机制

当你的团队成员将 mylib-1.0.0.jar 添加为项目依赖后，只需确保同目录下存在对应命名的 -sources.jar 和 -javadoc.jar（或通过 Maven 仓库自动下载），IntelliJ 会自动关联：

• 将鼠标悬停在类/方法上 → 显示 Javadoc 内容（来自 -javadoc.jar）
• 按 Ctrl+Click（Windows/Linux）或 Cmd+Click（macOS）→ 跳转至源码（来自 -sources.jar）
• 无需手动配置，前提是命名严格匹配（如 xxx-1.2.3-javadoc.jar）

⚠️ 注意事项：

• Javadoc 注释必须使用标准 /** ... */ 格式，并包含 @param、@return 等有效标签，否则生成内容为空；
• 若使用模块化（module-info.java），需在 javadoc 插件中启用 --module-path 支持；
• 发布到私有 Maven 仓库（如 Nexus/Artifactory）时，三件套会一并上传，下游依赖自动拉取全部资源；
• 切勿将 .java 源文件直接打包进主 JAR（如你尝试的“源码 JAR”误用），这会导致 NoClassDefFoundError 或类加载冲突。

✅ 总结

构建一个真正“开箱即用”的 Java 库，关键在于理解“运行时”与“开发时”资源的职责分离：主 JAR 专注执行，Javadoc JAR 和 Sources JAR 专注开发者体验。遵循 Maven/Gradle 的标准三件套实践，配合 IDE 的智能识别机制，即可让协作者零配置享受完整文档与源码导航——这才是工业级 Java 库交付的正确姿势。

终于介绍完啦！小伙伴们，这篇关于《生成Javadoc的Java库JAR方法详解》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布文章相关知识，快来关注吧！