正确呈现指向使用破折号而不是圆括号和逗号的外部html javadoc文档的javadoc方法链接
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脚本。
相关文章