如何消除与 scaladoc 中方法的链接的歧义？答案

【问题标题】：How to disambiguate links to methods in scaladoc?如何消除与 scaladoc 中方法的链接的歧义？
【发布时间】：2013-03-01 22:04:10
【问题描述】：

我正在使用 overloaded methods 记录一个 Scala 类。在 scaladoc cmets 中引用它们时如何区分它们？例如，如果我有

/**
 * The most important method is [[Doc.foo]].
 */
object Doc {
  def foo[A]: A = throw new UnsupportedOperationException;
  def foo[A,B >: A](x: A): B = x;
}

然后运行 sbt doc 我明白了

Doc.scala:1：警告：链接目标“Doc.foo”不明确。几个（可能重载的）成员适合目标：

对象文档中的方法foo[A,B>:A](x:A):B [选择]

对象文档中的方法foo[A]:Nothing

对链接使用foo[A,B >: A] 等无效。

【问题讨论】：

使用[[Doc.foo()]] 有用吗？我知道在 C# 中，当文档中的引用不明确时，您必须在使用不带参数的方法时使用 () 或拼出 argument types，例如foo(string)。也许这里是相似的......
@Trustme-I'maDoctor 这不起作用，抱怨：警告：找不到任何成员链接“Doc.foo()”。跨度>
欢迎 github.com/scala/docs.scala-lang 的 PR 向 docs.scala-lang.org/overviews/scaladoc/for-library-authors.html 添加相关文档

标签： scala scala-2.10 scaladoc method-names disambiguation

【解决方案1】：

以下似乎在 Scala 2.10 中可以解决问题。

/**
 * The most important method is [[Doc.foo[A]:A*]].
 */

这是 scaladoc 给我的一些提示：

[warn] Quick crash course on using Scaladoc links
[warn] ==========================================
[warn] Disambiguating terms and types: Prefix terms with '$' and types with '!' in case both names are in use:
[warn]  - [[scala.collection.immutable.List!.apply class List's apply method]] and
[warn]  - [[scala.collection.immutable.List$.apply object List's apply method]]
[warn] Disambiguating overloaded members: If a term is overloaded, you can indicate the first part of its signature followed by *:
[warn]  - [[[scala.collection.immutable.List$.fill[A](Int)(⇒A):List[A]* Fill with a single parameter]]]
[warn]  - [[[scala.collection.immutable.List$.fill[A](Int,Int)(⇒A):List[List[A]]* Fill with a two parameters]]]
[warn] Notes: 
[warn]  - you can use any number of matching square brackets to avoid interference with the signature
[warn]  - you can use \. to escape dots in prefixes (don't forget to use * at the end to match the signature!)
[warn]  - you can use \# to escape hashes, otherwise they will be considered as delimiters, like dots.

【讨论】：

我发现 ScalDoc 无法通过导入解析名称，这很可恶。我拒绝在文档 cmets 中使用完全限定名称。
显然，只有当我直接使用scaladoc时才会显示提示。我用了sbt，没有显示出来。
@Randall Schulz 这应该根据这个问题修复：issues.scala-lang.org/browse/SI-3695
唉，这对我来说并不总是适用于复杂的类型签名。但是对于更简单的，它确实如此。（我没有找到更复杂签名的解决方案。）
这个答案对我没有帮助。我试图消除具有相同类型参数但参数签名不同的“应用”方法的歧义。我需要它与 Intellij IDEA 'Quick Documentation' (Ctrl-Q) 一起查看方法的 scaladoc。

【解决方案2】：

我在IntelliJ 中发现非常有用的是右键单击您想放入 [[ ]] 的方法并选择“复制参考”。

步骤：

您找到了一个您想在其他地方引用的方法。

您右键单击方法名称并选择“复制参考”。

您将其粘贴到文档中的 [[ ]] 中（并在其旁边写上您选择的标签，例如“apply(String)”）。

瞧。

【讨论】：

这在 IntelliJ 2019.3.4 社区中对我有用。在阅读您的答案之前，我尝试了很多不同的方法，但无济于事。非常感谢。
并不总是适用于 Scala，但总的来说这是一个不错的功能！感谢分享

【解决方案3】：

通过研究 scaladoc 的文档，我找到了复杂签名的解决方案（显然是唯一的解决方案）。

不要在签名中使用空格
使用参数名称
对于参数类型和返回类型，在所有点前面加上一个反斜杠\
在签名末尾使用星号*
使用完整的签名（因为建议您使用不明确的签名）。这一步是可选的，你可以提前停止签名，只要你用*完成它

示例：

package org.my.stuff

class ReturnType

object Foo {
  class Bar {
    def lara(s: String): String = ???
    def lara(s: Foo.Bar): ReturnType= ???
  }
}

/** [[org.my.stuff.Foo$.Bar.lara(s:org\.my\.stuff\.Foo\.Bar):org\.my\.stuff\.ReturnType* The link to the right lara method]]
  */
object DocumentFooBarBingComplex {
}

【讨论】：

"不要在签名中使用空格" -- 如果有隐式参数怎么办？
唉，这确实行不通。您可以尝试在空格前添加 \，或者确保不需要写入隐式参数来消除代码歧义。

【解决方案4】：

我仍然对让这项工作有多么困难以及 scaladoc 本身缺乏文档感到惊讶。我决定搜索 scala 代码库本身，希望能找到一些有用的例子。我发现的最好的是https://github.com/scala/scala/blob/2.12.x/test/scaladoc/resources/links.scala。希望这对遇到此问题的其他人有用。

【讨论】：