如何在maven网站中从测试JavaDoc链接源类JavaDoc?

Question

我已经配置了maven-site-plugin和maven-javadoc-plugin（使用doclava doclet），现在我正在尝试通过mvn site命令在网站上生成正确的JavaDocs。在我的代码中，有几个JUnit测试类（位于src/test/java/my/package/*.java），它们的JavaDoc注释链接到源类（位于src/main/java/my/package/*.java）。问题是，在生成测试JavaDocs时，javadoc无法找到源类文档的位置。我尝试使用maven-javadoc-plugin的links和offlineLinks配置选项（在此处记录）告诉javadoc在哪里找到它，但没有成功。我希望javadoc生成相对链接，以便在离线查看生成的文档时能够正常工作（在浏览器中从/path/to/project/target/site/index.html浏览）。我不想禁用Test JavaDocs生成。

我的pom.xml | Mvn网站输出的摘录

此外，我是Java和Maven的新手

---

为了澄清问题，这里有一个例子。我有一个测试类GenerateATest，位于src/test/java/name/earshinov/PrefixCircuits/GenerateATest.java（抱歉，注释是俄语）。

package name.earshinov.PrefixCircuits;
// imports skipped

/**
 * Тестирование алгоритма построения вспомогательных подсетей типа A,
 * реализованного в классе {@link name.earshinov.util.PrefixCircuitGenerator},
 * по отдельным случаям, описанным в оригинальной статье
 */
public class GenerateATest {
// ...

链接的类PrefixCircuitGenerator位于src/main/java/name/earshinov/PrefixCircuits/PrefixCircuitGenerator.java中。运行mvn site后，我可以在target/site/apidocs/index.html找到源代码类的JavaDocs，以及在target/site/testapidocs/index.html找到测试JavaDocs。在测试JavaDocs中的GenerateATest文档中，我希望看到指向源代码类JavaDocs中PrefixCircuitGenerator文档的链接。但是，javadoc找不到我所引用的PrefixCircuitGenerator，因此它不会生成链接，并且相应的警告可在mvn site输出中看到：

[WARNING] /home/eugene/dev/java/PrefixCircuits-maven/src/test/java/name/earshinov/PrefixCircuits/GenerateATest.java:9: warning 101: Unresolved link/see tag "name.earshinov.util.PrefixCircuitGenerator" in name.earshinov.PrefixCircuits.GenerateATest

我的目的是（某种方式）告诉javadoc如何生成链接。将{@link name.earshinov.PrefixCircuits.PrefixCircuitGenerator}更改为{@link PrefixCircuitGenerator}并没有改变任何内容。

- Evgeny A.

---

首先，我建议您清理构建以防止在站点生成期间出现任何警告，如输出中所述。此外，哪种链接无法正常工作？指向生产代码的链接吗？ - khmarbaise

@khmarbaise 你所说的清理构建是什么意思？我在运行 mvn clean 后仍然收到相同的警告。关于我需要的链接，我会在主题中添加一个示例。 - Evgeny A.

您会收到来自 Maven Project Info Report 插件的警告，因为您在构建时未定义 Maven Project Info Report 插件的版本号。 - khmarbaise

@khmarbaise 我并没有显式地使用这个插件（它可能是 site-plugin 的一个依赖项），所以我不想仅为了定义其版本而将其包含在我的 POM 中。现在，我已经将 project-info-report-plugin 添加到报告插件列表中，因为我认为这是你推荐的。 - Evgeny A.

您可以使用“-link”参数告诉javadoc相关类的文档在哪里，但我不知道这如何转换为Maven。 - Paŭlo Ebermann

@Paŭlo，“-link”参数由javadoc插件的“links”配置选项控制。我尝试过了，但没有成功。可能是我用错了方法，但我们需要一个Maven或Maven&JavaDoc专家。 - Evgeny A.

Answer 1

刚有些时间进行实验。看起来doclava doclet不支持外部文档链接（没有实现-link命令行选项）。我通过从CLI运行javadoc发现了这一点。可能javadoc插件知道-link选项是特定于标准doclet的，因此如果使用替代doclet，则不会从pom.xml获取此选项的值并将其传递给javadoc通过命令行参数。因此不会生成错误。

- Evgeny A.