正确呈现指向使用破折号而不是圆括号和逗号的外部html javadoc文档的javadoc方法链接

2022-06-06 00:00:00 javadoc java maven maven-javadoc-plugin
使用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目标包括67891011

如果此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脚本。

相关文章