scala - 如何消除与 scaladoc 中方法的链接的歧义？

Question

我正在用重载方法记录一个 Scala 类。在 scaladoc 注释中引用它们时如何区分它们？例如，如果我有

/**
 * 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]etc. 不起作用。

Answer 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.

Answer 2

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

脚步：

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

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

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

4. 瞧。

Answer 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 {
}

Answer 4

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