为什么 JAR 文件不包含文档？

Question

我正在编写一个小型 Java 库，其中包含我通常包含在大多数 Android 应用程序中的相关代码。我决定将库导出为 jar 文件，然后将该文件放入我未来项目的 libs 文件夹中。

使用 Android Studio：

• 我创建了一个 Java 库模块并将代码放入其中。我在该方法之后添加了一些注释。
• 然后，我在 gradle 中运行 jar 任务，这在模块的 build/libs 目录中提供了 .jar 文件。

现在，当我在我的一个 Android 应用程序中使用这个 jar 时，除了Doc 部分之外，一切都按预期工作。当我将鼠标悬停在库的类和方法上时，我看不到我编写的文档注释。

Q1：我还漏掉了一步吗？
Q2： jar 文件应该没有注释吗？

Answer 1

javadoc是根据源代码中的javadoc 注释生成的文档。它们不是普通 JAR 文件的一部分，因为这会不必要地使 JAR 文件膨胀……其中包含运行代码的人不需要的内容。

javadoc 可以通过 Gradle 任务、命令javadoc（如果安装了 Java SDK）和各种其他工具生成。然后您可以使用网络浏览器阅读它们。

另一方面，IDE 通常可以在源代码中呈现 javadoc 注释并将其显示为弹出窗口等。（有些人会称之为“javadocs”，但我认为这是夸大其词，因为您通常无法导航文档......就像您可以阅读 javadoc 文档一样。）

为了呈现 javadoc 注释，IDE 需要源代码。JAR 文件（通常）不包含任何源代码或 javadoc。相反，处理此问题的正常方法是告诉 IDE 源代码在哪里，方法是将其指向源代码目录、包含源代码的 ZIP 文件或用于下载源代码的 URL。

（我不使用 Android Studio，所以我可以确切地告诉你如何做到这一点。但是，我想 IDE 的在线帮助解释了如何做到这一点......）

看来您的最终目标是以允许程序员查看 javadoc 注释的方式分发您的库。

做到这一点的简单方法是分发源代码。 此问答描述了如何让 Gradle 生成包含源代码的单独存档，或将源代码添加到包含已编译代码的 JAR ¹。

如果这是不可接受的，您可能需要将 javadoc 生成为 HTML ²，并以单独的 ZIP 文件形式提供 HTML 树，程序员可以使用 Web 浏览器解压缩并读取该文件。或者，将 javadoc 放在网站上。

^{1 - 我不会推荐这个。只想将 JAR 用作二进制文件的人很容易抱怨“膨胀”。
2 - 如果既不能提供源代码，也不能提供 javadoc HTML 文档，我认为没有一个务实的解决方案。}