正确地渲染Javadoc方法链接到使用破折号而非括号和逗号的外部HTML Javadoc文档。

Question

正确地渲染Javadoc方法链接到使用破折号而非括号和逗号的外部HTML Javadoc文档。

4

HTML javadoc文档是使用Java版本10及更高版本的javadoc工具生成的，方法链接/标签中使用括号()和逗号,，例如：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呈现正确的链接到使用破折号而不是括号和逗号生成HTML javadoc文档的项目的方法？默认情况下，使用括号和逗号会导致链接指向给定类页面的顶部而不是所需的方法部分。使用旧的javadoc工具为使用Java 10+的项目生成HTML不是解决方案，因为在这种情况下，对docs.oracle.com上的标准库（或任何其他使用Java 10+构建的外部项目）中的方法的链接将会失效。明确的解决方案必须仅适用于特定的<link>部分。

- morgwai

是的，谢谢。这大大澄清了你所遇到的问题。 - VGR

@VGR 不过，如果您知道如何使用破折号而不是括号使javadoc命令行工具生成到外部项目的链接，那将非常有帮助 :)（据我回忆，可以在maven-javadoc-plugin的xml配置中传递其他参数） - morgwai

@VGR 根据您的评论，我进一步澄清了原始帖子：谢谢！ - morgwai

1

我非常熟悉Maven。我正在准备答案，请耐心等待！敬请关注！;) - Gerold Broser

1

@GeroldBroser 我指的是 maven-javadoc-plugin 的一部分配置，即在 maven 的 pom.xml 中指定查找依赖项外部 javadoc 的位置。例如像这样：https://github.com/morgwai/grpc-scopes/blob/master/pom.xml#L110 - morgwai

显示剩余10条评论

2个回答

0

经过长时间的搜索，我倾向于认为在pom.xml中使用Ant将括号更改为连字符比寻找专用插件更容易：

<plugin>
  <artifactId>maven-antrun-plugin</artifactId>
  <executions>
    <execution>
      <phase>prepare-package</phase>
      <configuration>
        <target>
          <replaceregexp
              match='(&lt;a href="[^"]*grpc[^"]*)[(]([^)"]*)[)]("[^&gt;]* class="external-link")'
              replace="\1-\2-\3"
              flags="g">
            <fileset dir="${project.reporting.outputDirectory}/apidocs"
                     includes="**/*.html"/>
          </replaceregexp>
        </target>
      </configuration>
      <goals>
        <goal>run</goal>
      </goals>
    </execution>
  </executions>
</plugin>

很遗憾，我没有测试它的方法。

- VGR

我不得不从正则表达式中删除初始的<，因为Maven在抱怨：“_[致命] Non-parseable POM /home/morgwai/projects/grpc-utils/pom.xml：标记不允许在属性值内 - 非法<_”。即使没有它，正则表达式仍应足够准确。不幸的是，它没有任何效果：所有链接仍然使用括号呈现 :( - morgwai

@GeroldBroser VGR并没有解析整个HTML文档：他正在查找与正则表达式匹配的片段，这完全没问题。请参见您链接中的同一问题下的https://dev59.com/X3I-5IYBdhLWcg3wq6do#1733489。 - morgwai

@morgwai 抱歉，我的错误，XML属性值中不能出现 < 和 >；我已经编辑了我的答案，并分别用 < 和 > 替换了它们。 - VGR

@morgwai 我知道那个答案。只是想再次赞美这个计算机和写作艺术的杰作。 :) 你不认为 Ant 的 replaceregexp 在幕后执行 HTML 解析吗？然而，如果这个解决方案对你来说可以接受，那我也可以接受。到目前为止，我尝试过的解决方案都没有起作用，我心中下一个想法需要一天左右的时间开发，然后我必须问一下这是为你的公司服务的，我应该把发票寄到哪里。 :) - Gerold Broser

1

@GeroldBroser 目前VGR的解决方案不起作用：可能是正则表达式或其他细节问题。现在，由于VGR让我知道了Maven拼写，可以进行手动后处理，我稍后会尝试自己操作。当我在一些开源项目上工作时（之前链接的https://github.com/morgwai/grpc-scopes），我遇到了这个问题，所以没有好的候选人来开发票。老实说，我认为很多人之前都遇到过这个问题，所以应该有一个众所周知的解决方案。无论如何，非常感谢您和VGR的帮助！ :) - morgwai

显示剩余3条评论

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Gerold Broser · Accepted Answer

根据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)

如果您在使用不同的工具创建Javadoc文档的库中使用{@link ...}，而这些工具与您使用的工具不同（或使用了相同工具的不同版本），那么目前您将无法使用该链接。

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

如果这样不行，还有其他选择，比如在构建过程中运行外部程序，例如sed。让我考虑一下并尝试一些东西。我有信心能够想出一个可行的解决方案。但请耐心等待。现在是凌晨4点半，我想我需要睡几个小时。如果有人在此期间提出了解决方案，那就更好了（尽管我不认为会有，但谁知道呢... :)

方法一 - --release 选项

有一个javadoc的--release选项：

以下核心javadoc选项与相应的javac选项等效。有关使用这些选项的详细说明，请参见标准选项：

...

--release

"

javac 的 --release：

"

(Note: This is a technical term related to the Java programming language.)

“好笑了……不，这很尴尬：深层链接到 --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> Provide source compatibility with specified release”。至少现在在这里记录了。 ;)

方法2- Maven资源过滤 Maven的资源过滤也没有帮助，因为在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>
 */

我还不知道这些“保留字符”是否可以被转义，如果可以的话，应该如何转义。我找到了如何在 javadoc 内联标记（例如 {@code} 标记）中转义花括号，但是其中没有任何方法适用于 {@link ...}。

更新

第三种方法 - Maven XML 插件的 `xml:transform`

由于 Javadoc HTML 包含非 X(HT)ML 兼容的未关闭的 <meta ... > 和 <link ... >，因此无法使用此方法。

第四种方法 a) - 通过 GMavenPlus 插件的 Groovy 脚本

使用 FileVisitor，XPath - 如果它可以与不符合X(HT)ML标准的HTML一起工作，或者使用任何其他可行的方法。

XPath不起作用：[致命错误]: 18:3：元素类型“link”必须由匹配的结束标记“”终止。 方法#4 b) - 恢复其中一个maven-javascript-plugin 或 Maven Javascript Plugin，添加目标javascript:execute并使用具有其CSS选择器和DOM操作的JS脚本。

正确地渲染Javadoc方法链接到使用破折号而非括号和逗号的外部HTML Javadoc文档。

更新

第三种方法 - Maven XML 插件的 xml:transform

第四种方法 a) - 通过 GMavenPlus 插件 的 Groovy 脚本

第三种方法 - Maven XML 插件的 `xml:transform`

第四种方法 a) - 通过 GMavenPlus 插件的 Groovy 脚本