应该如何分发库的 Javadoc？答案

【问题标题】：How should one distribute the Javadoc for a Library?应该如何分发库的 Javadoc？
【发布时间】：2011-04-22 07:11:09
【问题描述】：

我正在编写一个自定义库。它被构建到一个 .jar 档案中。我完全能够生成 javadoc，但我不知道应该如何分发它？

与库放在同一个 .jar 中
将其放入不同的 .jar 中
其他方式？

以及如何将 javadoc 包含在另一个使用我的 lib 的项目中？

如果我把它放在同一个 .jar 中，我应该在清单中写一些东西吗？
如果在单独的 .jar 中，将其包含在项目中是否足够？

我使用的是 NetBeans 9.1。

【问题讨论】：

标签： java jar javadoc

【解决方案1】：

我会在单个存档（zip 或 tar.gz）中包含库 .jar 和文档以及其他内容，例如 README、许可证文件等

mylib-1.0.1.tar.gz ，其中包含：

mylib-1.0.1/
           ├── javadoc
           │   └── index.html  (and all other javadoc files under here)
           ├── mylib-1.0.1.jar
           └── README

您可以将压缩的 javadoc 添加到 mylib-1.0.1-javadoc.jar（或 zip）中，而不是存档中扩展的 javadoc/ 子目录，这两个选项都很常见。

mylib-1.0.1/
           ├── mylib-1.0.1-javadoc.jar
           ├── mylib-1.0.1.jar
           └── README

【讨论】：

javadoc 包含许多文件，所以我更喜欢压缩和存档。另一方面，这是我的错，我认为它可能很特别，因为我认为 netbeans 中的“添加 jar/zip”命令仅适用于库，但它几乎适用于任何资源。谢谢！
如果您这样做，Eclipse 能够从引用链接到 Javadoc。确实不错的方法。这也是 Maven 存储库倾向于做的事情：search.maven.org/#browse|1803601404

【解决方案2】：

将 JavaDocs 保存在单独的存档中是一种普遍的做法。或者更常见的是，在一个名为“docs”的目录中。你不需要用 html 和 js 文件来膨胀你的图书馆档案。

为什么要在项目中包含生成的 JavaDocs [html + js]？只要源代码 JavaDoc cmets 就位，使用您的库的人只需将鼠标悬停在任何现代 IDE 中，就能看到它们

更新
根据下面南达的评论，我检查了同样的内容，他是正确的。在我的项目中，我实际上已将“doc”文件夹中的 Javadocs 附加到存档中，以便能够在鼠标悬停时查看它们。

【讨论】：

不正确...如果您正常编译 java 类，您将丢失所有 cmets。即使是IDE也无法恢复。您应该在另一个 jar IMO 中包含源代码。

【解决方案3】：

另一种方式：对我来说这是最好的选择：（添加到 build.xml。我已经在 NetBeans IDE 7.0 和 7.2.1 上对其进行了测试）（在 Automatically generating source and doc jars in Netbeans 上找到它）

<target name="-post-jar" description="bundle sources and javadoc in a jar" depends="javadoc">
<jar compress="${jar.compress}" basedir="${src.dir}" jarfile="${dist.dir}/${application.title}-sources.jar"/>
<jar compress="${jar.compress}" basedir="${test.src.dir}" jarfile="${dist.dir}/${application.title}-test.jar"/>
<jar compress="${jar.compress}" basedir="${dist.javadoc.dir}" jarfile="${dist.dir}/${application.title}-javadoc.jar"/>

这将创建四个 jar，一个用于应用程序，一个用于源代码，一个用于测试，一个用于 javadoc。

【讨论】：