应如何分发库的 Javadoc？

Question

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

1. 将其与库放在同一个 .jar 中
2. 将其放在不同的 .jar 中
3. 还有其他方式吗？

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

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

我正在使用 NetBeans 9.1。

Answer 1

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

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/ 子目录，您可以将压缩的 javadoc 添加到 mylib-1.0.1-javadoc.jar （或 zip） 中，这两个选项都很常见。

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

Answer 2

通常的做法是将 JavaDocs 保存在单独的存档中。或者更常见的是，在名为“docs”的目录中。您不想不必要地用 html 和 js 文件来膨胀您的库的存档。

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

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

Answer 3

另一种方式：
对我来说，这是最好的选择：（添加到 build.xml。我已经在 NetBeans IDE 7.0 和 7.2.1 上测试了它）（在 在 Netbeans 中自动生成源代码和文档 jar )

<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。