java - javadoc中模块之间的链接

Question

Java 10 中 javadoc 命令的 -link 选项对我来说无法始终如一地使用模块。

具体来说，它在依赖模块名称与其导出的包名称相同的情况下不起作用

我运行以下命令

/opt/jdk-10.0.1/bin/javadoc -html5 
 -subpackages uk.co.sr.vcher.service \
 --source-path src/service \
 --module-path lib:app -d javadoc/service \
 -link ../auth -link ../db -link ../models \
 -link ../core -link ../render \
 -link https://docs.oracle.com/javase/10/docs/api \
 -linksource src/service/uk/co/sr/vcher/service/Service.java \
  src/service/uk/co/sr/vcher/service/ServiceImpl.java \
  src/service/module-info.java

这就是为包 uk.co.sr.vcher.service 中的两个类生成 javadoc，它们位于 src/service 下，并将文档链接到我的应用程序中的其他 5 个模块，加上jdk 文档

我构建的模块jar在app/，外部依赖在lib/

Javadoc 成功并生成 HTML。但是我的应用程序的某些(不是全部)其他模块中的类链接已损坏，缺少包的路径目录。

我在下面展示的是 uk.co.sr.vcher.service.ServiceImpl 的一个构造函数的一段 HTML 输出。它有四个参数:File、ConnectionSource、Coder 和 ApplicationConfig

为了便于阅读，我删除了附加到 ServiceImpl 的链接，并添加了一些空格。这是我所关注的四种参数类型的链接。

File 是 java.io.File 并正确链接到 docs.oracle.com

ConnectionSource 是 uk.co.sr.vcher.db.ConnectionSource 并且工具提示正确显示包，并且链接转到正确的 javadoc模块 uk.co.sr.db，链接是错误的，因为它不包含包的路径

Coder 是来自模块 uk.co.sr.vcher.core 的 uk.co.sr.vcher.Coder。在这种情况下，链接是正确的，指向 core/uk/co/sr/vcher/Coder.html

ApplicationConfig 和 Coder 一样，来自模块 uk.co 中的包 uk.co.sr.vcher。 sr.vcher.core，链接正确。

在我的整个项目中，两个模块的链接是正确的，但所有其他模块的链接都因缺少包路径而损坏。

我以相同的方式为我的每个模块创建了 javadoc。它们在其基础上包含元素列表文件，而不是包列表文件。 uk.co.sr.vcher.service 模块依赖于 uk.co.sr.vcher.db 和 uk.co.sr.vcher.core 模块。

据我所知，我可以成功链接到的模块与我不能成功链接到的模块之间的区别在于“好的”模块不在其他任何东西的子包中。即模块 uk.co.sr.vcher.db 包含包 uk.co.sr.vcher.db 这是包 uk.co.sr 的子包.vcher，包含在模块 uk.co.sr.vcher.core 中。但这不应该破坏任何东西。

<span class="memberNameLink">
ServiceImpl</span>(
<a href="https://docs.oracle.com/javase/10/docs/api/java/io/File.html?is- 
external=true"
title="class or interface in java.io" 
class="externalLink">File</a> workDirectory,

<a href="../../../../../../db/ConnectionSource.html?is- 
external=true" 
title="class or interface in uk.co.sr.vcher.db" 
class="externalLink">ConnectionSource</a> db,

<a href="../../../../../../core/uk/co/sr/vcher/Coder.html?is- 
external=true" 
title="class or interface in uk.co.sr.vcher" 
class="externalLink">Coder</a>&nbsp;coder,
<a href="../../../../../../core/uk/co/sr/vcher/ApplicationConfig.html?is- 
external=true" 
title="class or interface in uk.co.sr.vcher" 
class="externalLink">ApplicationConfig</a> config)

更新:我在 https://github.com/andrewmcguinness/javadoc_issue 上放了一个最小的示例项目——三个 java 类，三个模块——它显示了同样的问题。

更新 2:我将原因归结为包 uk.co.sr.vcher.db 的名称与模块的名称相同 英国.co.sr.vcher.db。将模块名称更改为 uk.co.sr.vcher.pdb 可以修复它。我仍然想知道这是 jdk 错误还是我做错了什么。

Answer 1

我将继续称之为 javadoc 错误。我不太了解 javadoc 代码，但看起来很可能它在内部将包和模块存储在同一个字典中，因此如果模块与包同名，它会覆盖包信息。然后当它必须查找包的路径时，它会失败并默认为空字符串。

我已经 reported the bug to Oracle .如果有任何有用的结果，将会更新。

解决方法是将您的模块(在我的示例中为 uk.co.sr.vcher.db)重命名为不是导出包之一的名称。