根据RFC 3986 https://datatracker.ietf.org/doc/html/rfc3986两种变体都是有效的。
例如,带有 Java
https://docs.oracle.com/javase/9/docs/api/java/lang/Object.html#equals-java.lang.Object- 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) https://docs.oracle.com/javase/10/docs/api/java/lang/Object.html#equals(java.lang.Object)
If you {@link ...}
如果某个库的 Javadoc 使用与您不同的工具来创建其 Javadoc(或使用同一工具的不同版本),那么您目前运气不好。
如果我们确实在 Javadoc 工具中找不到相应的选项(我认为我们不会,因为为什么外部链接的处理方式应该与内部链接不同),我首先想到的是Maven 资源插件。它具有以下特点资源过滤 https://maven.apache.org/plugins/maven-resources-plugin/examples/filter.html(这是一个不好的命名,因为事实上它是字符串插值)也许这可以用来相应地替换字符。
如果这不起作用,还有其他选择,例如运行外部程序,例如sed
,在构建过程中。让我想一下并尝试一些事情。我相信我能想出一个可行的解决方案。不过,请耐心等待。现在是凌晨 4:30,我想我很快就需要睡几个小时了。如果有人同时提出解决方案,那就更好了(虽然我不这么认为,但谁知道呢......:)
方法#1 –--release
option
There's javadoc's --release https://docs.oracle.com/en/java/javase/11/tools/javadoc.html#GUID-9D532574-1CDB-4D30-99F3-A308DCAEE55F__GUID-8E6B3C5F-B4AB-4253-9157-9476500E424D option:
以下核心javadoc
选项相当于对应的javac
选项。看标准选项 https://docs.oracle.com/en/java/javase/11/tools/javac.html#GUID-AEEC9F07-CB49-4E96-8BC7-BCC2C7F725C9__STANDARDOPTIONSFORJAVAC-7D3D9CC2有关使用这些选项的详细说明:
javac's --release https://docs.oracle.com/en/java/javase/11/tools/javac.html#GUID-AEEC9F07-CB49-4E96-8BC7-BCC2C7F725C9__GUID-D343F6B4-3FDD-43A8-AD24-43DD70214471:
[嗯,这很有趣......好吧,不,这很尴尬:深层链接--release https://docs.oracle.com/en/java/javase/11/tools/javac.html#GUID-AEEC9F07-CB49-4E96-8BC7-BCC2C7F725C9__GUID-D343F6B4-3FDD-43A8-AD24-43DD70214471和它的Note: ... https://docs.oracle.com/en/java/javase/11/tools/javac.html#GUID-AEEC9F07-CB49-4E96-8BC7-BCC2C7F725C9__GUID-947ACE0E-6307-48C6-B820-EC7F929EBDF0最终不起作用,因为跳转到它们后的几分之一显然是 JS(AJAX?)开始发挥作用,页面最终到达顶部。我想太阳微系统公司 https://en.wikipedia.org/wiki/Sun_Microsystems back!]
--release release
针对特定 VM 版本的公共、受支持和记录的 API 进行编译。支持的release
目标是6
, 7
, 8
, 9
, 10
, and 11
.
If this javadoc --release
解决您的问题,我们不必进一步考虑手工解决方案。
Update: The --release
/<release>
选项并不能解决问题。只是指定链接目标版本,如下所示https://docs.oracle.com/javase/<version>/docs/api/...
。上面的文档在这方面并没有太大帮助,maven-javadoc-plugin doc https://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html#release也不是:“提供与指定版本的源兼容性“。至少现在已经记录在这里了。;)
方法 #2 – Maven 资源过滤
Maven的资源过滤 https://maven.apache.org/plugins/maven-resources-plugin/examples/filter.html也没有帮助,因为在 Javadoc 注释中,仅具有一个参数的方法的方法引用可能如下所示:
/**
* <p>Link to {@link Logger#info}</p>
* <p>Link to {@link Object#equals}</p>
*/
对于字符串插值,我们需要${...}
(或者不知名和不寻常的@...@ https://maven.apache.org/plugins/maven-resources-plugin/examples/escape-filtering.html) 定义。
它可以(理论上)以显式形式工作:
/**
* <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>
*/
我(还不)不知道这些“保留字符”是否可以转义,如果可以,如何做到这一点。我发现如何转义 javadoc 内联标记中的大括号,例如 {@code} 标记 https://stackoverflow.com/q/647195/1744774但那里没有任何东西适用于{@link ...}
(yet).
UPDATE
方法 #3 – Maven XML 插件xml:transform https://www.mojohaus.org/xml-maven-plugin/transform-mojo.html
不起作用,因为 Javadoc HTML 包含不符合 X(HT)ML 的未封闭内容<meta ... >
s and <link ... >
s.
方法 #4 a) – Groovy 脚本通过GMavenPlus 插件 https://groovy.github.io/GMavenPlus/plugin-info.html
Using 文件访问者 https://docs.oracle.com/javase/tutorial/essential/io/walk.html、 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-插件 https://github.com/tschueller/maven-javascript-plugin or Maven JavaScript 插件 http://hammerfest.sourceforge.net/maven-javascript-plugin/, ...
...添加一个目标javascript:execute
并使用 JS 脚本及其 CSS 选择器和 DOM 操作。