正确呈现指向使用破折号而不是圆括号和逗号的外部html javadoc文档的javadoc方法链接 [英] correctly render javadoc method links to external html javadoc documents that use dashes instead of parentheses and commas

问题描述

使用Java版本10及更高版本的javadoc工具生成的HTMLjavadoc文档在方法链接/标签中使用圆括号和逗号，例如：https://docs.oracle.com/javase/10/docs/api/java/lang/Object.html#wait(long,int)。
但是，旧版本会用破折号-替换这些字符，例如：https://docs.oracle.com/javase/9/docs/api/java/lang/Object.html#wait-long-int-。
(感谢this answer解释格式取决于javadoc版本)

现在，当使用Java版本10+构建项目时，我如何才能使maven-javadoc-plugin呈现正确的方法链接，这些方法来自使用旧版本生成其HTMLjavadoc文档的项目？(即，当maven-javadoc-plugin的配置节中的pom.xml中的<link>标记之一指向一组使用破折号而不是圆括号和逗号的HTMLjavadoc文档时)。 默认情况下，使用圆括号和逗号，这会导致链接指向给定类页面的顶部，而不是所需的方法部分。

使用较旧的javadoc工具为使用Java 10+的项目生成HTML不是一种解决方案，因为在这种情况下，从docs.oracle.com的标准库到方法的链接(或到使用Java 10+构建的任何其他外部项目的链接)将被破坏。最终解决方案必须仅适用于特定的<link>节。

推荐答案

根据RFC 3986，这两种变体都有效。

例如，带有Java<；=9参数的方法的URL片段如下：

https://docs.oracle.com/javase/9/docs/api/java/lang/Object.html#equals-java.lang.Object-

对于Java 10-17，它们如下所示：

https://docs.oracle.com/javase/10/docs/api/java/lang/Object.html#equals(java.lang.Object)

如果您{@link ...}使用与您不同的工具(或使用同一工具的不同版本)创建其Javadoc的库的Javadoc，则您目前运气不佳。

如果我们真的没有在Javadoc工具中找到相应的选项(我认为我们不会找到，因为为什么外部链接的处理方式应该与内部链接不同)，我首先想到的是Maven Resources插件。它具有resource filtering的功能(这是一个糟糕的命名，因为实际上它是字符串内插)，也许这可以用来相应地替换字符。

如果这不起作用，还有其他选择，例如在构建期间运行外部程序。让我想一想，试一试。我相信我能想出一个可行的解决方案。不过，请耐心等待。现在是凌晨4：30。现在就在这里，我想我很快就需要几个小时的睡眠。如果有人在此期间拿出解决方案，那就更好了(虽然我不这么认为，但谁知道呢……：)

方法1---release选项

有javadoc's --release选项：

以下核心javadoc选项等同于对应的javac选项。有关使用这些选项的详细说明，请参阅Standard Options：

• ...
• --release

javac's --release：

[好吧，这很有趣……好吧，不，这很令人尴尬：到--release及其Note: ...的深层链接最终并不起作用，因为跳转到它们几厘米后显然是JS(AJAX？)开始使用，页面最终落在它的顶部。我要Sun Microsystems回来！]

--release release

针对特定的VM版本编译公共的、受支持的和有文档记录的API。支持的release目标包括6、7、8、9、10和11。

如果此javadoc --release解决了您的问题，则无需进一步考虑手动解决方案。

更新：--release/<release>选项不能解决问题。它只是指定https://docs.oracle.com/javase/<version>/docs/api/...中的链接目标版本。上面的文档在这方面没有太大帮助，maven-javadoc-plugin doc也没有："；<；Release&>提供与指定版本&Quot；的源代码兼容性。至少它现在被记录在这里了。；)

方法2-Maven资源筛选

Maven's resource filtering也没有帮助，因为在Javadoc注释中，只有一个参数的方法的方法引用可能如下所示：

/**
 * <p>Link to {@link Logger#info}</p>
 * <p>Link to {@link Object#equals}</p>
 */

对于字符串内插，我们需要${...}(或不常见和不常见的@...@)定义。

它将(在理论上)以显式形式运行：

/**
 * <p>"${(}" and "${)}" replaced by '-', if the additional '{' and '}' don't conflict with Javadoc comment's tags – but it seems they do</p>
 * <p>Link to {@link Logger#info${(}String${)}}</p>
 * <p>Link to {@link Object#equals${(}Object${)}}</p>
 *
 * <p> "@(@" and "@)@" replaced by '-'</p>, if the additional '@'s don't conflict with Javadoc comment's tags – but it seems they do</p>
 * <p>Link to {@link Logger#info@(@String@)@}</p>
 * <p>Link to {@link Object#equals@(@Object@)@}</p>
 */

我还不知道这些&q；保留字符&是否可以转义，如果可以，如何转义。我找到了How do you escape curly braces in javadoc inline tags, such as the {@code} tag，但其中的任何内容都无法与{@link ...}一起使用。

更新

方法3-Maven XML插件xml:transform

不起作用，因为Javadoc HTML包含非X(HT)ML兼容的未关闭<meta ... >和<link ... >%s。

方法4 a)-通过GMavenPlus Plugin

编写Groovy脚本

使用FileVisitor，XPath-如果它与非X(HT)ML-兼容的HTML一起工作-或其他任何工作方式。

XPath不工作：[Fatal Error] :18:3: The element type "link" must be terminated by the matching end-tag "</link>".

方法4 b)-恢复maven-javascript-plugin或Maven Javascript Plugin之一，...

.添加一个目标javascript:execute并使用带有其CSS选择器和DOM操作的JS脚本。

这篇关于正确呈现指向使用破折号而不是圆括号和逗号的外部html javadoc文档的javadoc方法链接的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！