仅使用 JRE 生成 javadoc

Question

我希望能够为我的 maven 项目生成 javadoc，即使在 JRE 而不是 JDK 下运行时，也可以找到 maven 调用的 javadoc 命令。换句话说，除了 JRE 中的内容以及 Maven 可以下载和用作工件的内容之外，不依赖任何东西。

是否有任何简单的方法可以使用 Maven 生成 javadocs，而无需使用仅在 JDK 中找到的代码？

---

编辑：显然理解为什么我想这样做很重要。我们是一个大型组织中的一个小团队，我们的产品套件每年发布一次，然后我们的客户会在他们方便的时候对其进行升级（由于部署规模庞大，这既昂贵又耗时，因此通常会跳过一个或多个版本），我们以能够在短时间内为客户正在运行的任何版本的现有部署提供错误修复和新功能为生。举个例子，我最近对我五年前写的一个组件做了一个错误修复，从那以后它基本上没有受到影响。

因此，我们构建过程的长期稳定性以及能够使用新版本的 Java 对我们来说非常重要。我们已经将完整的构建环境迁移到 Maven——它在 Maven Central 中为我们购买了永久冻结的工件——现在已经开始研究我们还需要做什么。

随着最近宣布 javac 的未来版本将不支持旧目标 (http://openjdk.java.net/jeps/182)，我们得出的结论是，我们的长期目标是尽量减少对底层 Java 环境的依赖，最好只对普通 JRE。我们正在使用 Maven Central 提供的 Eclipse 编译器完全替换 JDK 中的 javac，现在我们来看看 javadoc 的生成。

Answer 1

获取JavaDoc from the OpenJDK 的源代码，并使用所有相关的JavaDoc 类从中构建您自己的JAR。编写一个依赖于您的 JAR 的 maven 插件，并从中调用 com.sun.tools.javadoc.Main.main。

看起来不像you need to open up your sources when using OpenJDK's classes，您应该可以不受严格限制地分发生成的插件。

即使条款不包括这些工具，您也可以为maven 编写一个开源 GPL-2 插件，并使其成为您根据 GPL-2 分发的单独产品。然后，您的产品将使用 maven plugin:download 下载并安装插件，从而将您的 JavaDoc 插件与其余代码分开。

当然，在遵循此建议之前，您应该由您的法律部门执行此建议。

Answer 2

1. 旁白（不直接回答你的问题）：

   Eclipse 开发指南建议同时使用 Eclipse 编译器和 JDK 工具（用于 javadoc 菜单选项）。

   http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.jdt.doc.user%2Freference%2Fref-export-javadoc.htm

   Eclipse Generate Javadoc Wizard: what is "Javadoc Command"?

   从你的 cmets 看来，你显然不想走这条路，这是你的权利:)

2. 回答您的问题。您可以从构建工具中调用一些开源/免费的 javadoc 工具：

   • 专业

     • Doxygen

       Doxygen vs Javadoc
       http://doodleproject.sourceforge.net/mavenite/doxygen-maven-plugin/

     • Docflex Doclet（需要 JDK）

       http://www.filigris.com/print.php?printfile=/products/docflex_javadoc/docs/integrations.php#maven_2.2.x_3.0.x

   • 次要

     • Javadoc2Help

       （创建您自己的 Maven 命令/插件？）

     • Javadoq

       （创建您自己的 Maven 命令/插件？）

   优点：在 JDK 之外工作。有些文档比 javadoc 更丰富。
   缺点：与 javadoc 相比，可能有一些非标准行为（对您来说可能不是问题）。

Answer 3

您可以使用名为doxygen 的产品。它通常用于为 C++ 或其他没有内置 javadoc 产品的语言创建文档。

您可以设置 doxygen 来读取 javadoc 注释并生成与 javadoc 类似的输出。

Answer 4

生成 java 文档的命令实际上称为 javadoc，它仅适用于 JDK。

Answer 5

来自Javadoc FAQ：

String[] javadocargs = { "-d", "docs",
                         "-sourcepath", "/home/user/src",
                         "java.applet" };
com.sun.tools.javadoc.Main.main(javadocargs);

tools.jar 需要在您的类路径中。

Answer 6

我们提供了一个名为 DocFlex/Javadoc 的工具，Glen Best 已经提到了here（虽然有点不正确）。

但在深入探讨之前，我想先介绍一下这一切的含义。

基本上，Javadoc（由 JDK 提供）是两个东西的调用者：

1. Java 解析器
2. 一个 doclet

Javadoc 首先调用 Java 解析器以收集有关 Java 源的信息，并从中构建一个类似 DOM 的结构，以 Doclet API 的形式表示。 然后，它调用一个doclet。这是一个 Javadoc 插件，它使用 Doclet API 作为数据源来生成任何类型的输出。

您所看到的标准JavaDoc 是由Standard Doclet 生成的。 所以，你可以想象 doclet 是整个 Javadoc 实现中最大的部分。

现在，关于我们的 DocFlex/Javadoc 软件。 本质上，它是一种快速开发特殊 doclet 的工具，它利用 我们用于模板驱动的文档生成器的更通用的技术。 （实际上，我们的重点是远离 Javadoc 的东西。所以，它更像是主要内容的副产品。

在我们的解释中，doclet 本身（作为文档生成器）以特殊模板集的形式进行编程。这些模板更类似于 XSLT 脚本，但只是概念性的（我们不会在后台某处使用 XSLT）。 Doclet API 的类 DOM 组织使我们能够利用对我们的技术通用的类似 XSLT/XPath 的方法。 因此，每个 doclet 由两部分组成：

1. 模板解释器
2. 模板集

这里，模板集是一个可互换的部分（这实际上是我们工具的重点）。

目前，我们提供了一个即用型 JavadocPro 模板集，它生成与标准 JavaDocs 等效的 HTML 输出（标准 Doclet 中没有一些重要的额外功能）。在这里，您可以看到使用它生成的demo JavaDoc：

整个DocFlex/Javadoc 是商业产品。 但我们也提供了一个名为 DocFlex/Doclet 的轻量版，它是免费的。 它只包括模板解释器和一些现成的模板集（包括JavadocPro）。因此，您可以使用它来生成与标准文档（HTML 格式）非常相似的 JavaDoc 以及 RTF 文档。

---

现在，关于主要问题。我们的工具可以在没有JDK的情况下使用吗？

没有。因为，作为一个 Javadoc 插件（我们工具的 doclet 部分），它仍然需要 Javadoc。

另一方面，要使其完全独立于 JDK，缺少的是 Java 解析器， 我们不需要一个成熟的 Java 解析器，因为我们没有生成可执行代码。 我们需要的是轻量级的，能够构建类似 Doclet API 的结构。

如果我们知道对这种东西的需求可能是什么，我们可以考虑开发一个。 还有其他问题吗？通过电子邮件告诉我们（在我们的website 上找到）！

Answer 7

为什么不下载 javadoc 源代码？ http://docs.oracle.com/javase/6/docs/technotes/guides/javadoc/standard-doclet.html#source

并在 maven 中重建它以满足您的需要