java 库的 jar 文件本身不包含 javadoc（仅含编译后的字节码），文档需单独生成并以 *-javadoc.jar 形式发布；ide（如 intellij）通过约定命名自动关联，实现悬停提示与源码跳转。
在 Java 生态中，一个专业、可协作的库（Library）不仅需要提供功能完备的 .jar（含 .class 文件），还必须配套提供可被 IDE 识别的 Javadoc 和源码支持——但这三者（主 JAR、Javadoc JAR、Sources JAR）是物理分离、逻辑协同的三个独立构件，而非打包进同一个 JAR 中。
✅ 正确做法：三件套分离发布
标准 Maven/Gradle 构建流程会生成以下三个 JAR 文件（命名遵循约定）：
| 文件名示例 | 用途 | 是否必需 |
|---|---|---|
| mylib-1.0.0.jar | 运行时字节码（核心功能） | ✅ 必须 |
| mylib-1.0.0-sources.jar | 原始 .java 源文件（支持 IDE 跳转） | ⚠️ 强烈推荐 |
| mylib-1.0.0-javadoc.jar | 生成的 HTML 文档（经 javadoc 工具编译） | ⚠️ 强烈推荐 |
? 为什么不能把 Javadoc 编译进主 JAR？ 因为 Javadoc 是纯注释内容（/** ... */），在 javac 编译过程中不会生成任何字节码，也不会嵌入 .class 文件。它本质是独立的 HTML/JS/CSS 静态资源集，体积可能远超主 JAR —— 强行合并将显著增大部署包，违背“运行时最小化”原则（类似 C/C++ 的 .so/.dll 不含 Doxygen 文档）。
? 示例：使用 Maven 自动生成三件套
在 pom.xml 中添加以下插件配置：
org.apache.maven.plugins maven-source-plugin 3.2.1 attach-sources jar-no-fork org.apache.maven.plugins maven-javadoc-plugin 3.5.0 attach-javadocs jar
执行命令打包：
立即学习“Java免费学习笔记（深入）”；
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 库交付的正确姿势。
