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

Question

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

使用Android Studio：

• 我创建了一个Java Library模块并将我的代码放入其中。我在this之后添加了一些评论方法。
• 然后，我在gradle中运行了jar任务，它给了我模块的build / libs目录中的.jar文件。

现在，当我在我的一个Android应用程序中使用此jar时，Everything按预期工作，除了 Doc部分。当我将鼠标悬停在我的库的类和方法上时，我看不到我写的Doc评论。

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

Answer 1

javadocs 是源代码中 javadoc comments 生成的文档。

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

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

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

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

这里的最终目标似乎是以允许程序员查看javadoc注释的方式分发库。

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

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

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

Answer 2

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

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

然后运行：

gradle javadocJar

看看是否有帮助。

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

jar {
    from javadoc.destinationDir
}

jar.dependsOn javadoc

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