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

【问题标题】：Why JAR Files Do Not Contain Documentation?为什么 JAR 文件不包含文档？
【发布时间】：2015-11-16 02:48:22
【问题描述】：

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

使用 Android Studio：

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

Q1：我错过了另一个步骤吗？
Q2： jar 文件是否应该没有 cmets？

【问题讨论】：

【解决方案1】：

有一个单独的 Gradle 任务来生成 javadoc。尝试添加以下内容：

task javadocJar(type: Jar, dependsOn:javadoc) { 
 classifier = 'javadoc' 
 from javadoc.destinationDir }

然后运行：

gradle javadocJar

看看有没有帮助。

除了上述之外，您还可以尝试添加以下内容以生成包含已编译类和 javadoc 的单个 jar：

jar {
    from javadoc.destinationDir
}

jar.dependsOn javadoc

我不知道将所有东西捆绑在同一个 jar 中是否是正确的决定。我更喜欢将 jar 分开，也许可以找到另一种方法让 IDE 使用 javadoc jar 文件。也许尝试将 javadoc jar 添加为模块的另一个依赖项。

【讨论】：

好的。我找到了任务，但它似乎只是生成了一个 html 版本的文档。
我应该将任务添加到库 build.gradle 中，对吧？
图书馆是什么意思？它应该被添加到您项目的 gradle 文件中。
我是指模块（库）或顶层（项目）的 gradle 文件？
先试试这个模块。如果这有助于您可以使用 allprojects/subprojects 添加到所有模块，如下所述：docs.gradle.org/current/userguide/multi_project_builds.html.

【解决方案2】：

javadocs 是从源代码中的javadoc cmets 生成的文档。它们不是普通 JAR 文件的一部分，因为这会使 JAR 文件不必要地膨胀……其中包含有人运行代码不需要的东西。

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

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

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

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

您的最终目标似乎是以允许程序员查看 javadoc cmets 的方式分发您的库。

执行此操作的简单方法是分发源代码。 This Q&A 描述了如何让 Gradle 生成包含源代码的单独存档，或将源代码添加到包含已编译代码的 JAR¹。

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

^{1 - 我不推荐这个。只想将 JAR 用作二进制文件的人可能会抱怨“臃肿”。

2 - 如果既不提供源代码也不提供 javadoc HTML 文档，我认为没有实用的解决方案。}

【讨论】：