无法为重载方法创建 ScalaDoc 链接答案

【问题标题】：Cannot create ScalaDoc link for overloaded method无法为重载方法创建 ScalaDoc 链接
【发布时间】：2014-04-20 11:53:10
【问题描述】：

我在使用重载时遇到了 ScalaDoc 不接受方法链接的问题。

一个独立的例子：文件project/build.properties：

sbt.version=0.13.2

文件build.sbt：

scalaVersion := "2.11.0"

文件src/main/scala/Foo.scala：

package foobar

/** @see [[Bar#foo]]
  * @see [[Bar#bar]]
  */
case class Foo()

abstract class Bar {
  def foo: Int

  def bar: Foo
  def bar(x: Option[Int]): Foo
}

当我运行sbt doc 时，[[Bar#foo]] 链接很好，但不接受[[Bar#bar]] 链接：

[warn] .../src/main/scala/Foo.scala:3: The link target "Bar#bar" is ambiguous. 
       Several members fit the target:
[warn] (x: Option[Int]): foobar.Foo in class Bar [chosen]
[warn] : foobar.Foo in class Bar
[warn] 
[warn] 
[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.
[warn] /** @see [[Bar#foo]]
[warn] ^
[warn] one warning found

所以使用“速成课程”，我尝试了各种各样的东西，例如

[[Bar#bar:Foo*]]
[[Bar!.bar:Foo*]]
[[foobar.Bar!.bar:foobar.Foo*]]

这些都不起作用。既不使用其他重载变体：

[[Bar#bar(Option[Int])]]
[[Bar#bar(Option[Int]):Foo]]
[[Bar!.bar(Option[Int]):Foo*]]

所以要么（像往常一样......）scala-doc完全坏了，还是我做错了什么？

【问题讨论】：

标签： scala overloading scaladoc

【解决方案1】：

以下内容对我有用。使用完全限定的参数和返回类型，其中的点以\ 为前缀。

[[Bar#bar:foobar\.Foo* The first bar method without argument]]
[[Bar#bar(x:Option[Int]):foobar\.Foo* The second bar method with argument]]

【讨论】：

【解决方案2】：

我试过了：

package foobar

/** @see [[Bar#foo]]
  * @see [[Bar!.bar*]]
  * @see [[[Bar!.bar(x:Option[Int])*]]]
  */
case class Foo()

abstract class Bar {
  def foo: Int

  def bar: Foo
  def bar(x: Option[Int]): Foo
}

虽然我收到相同的警告，但生成的文档带有两个 bar 方法的链接。

所以我猜 scala-doc 并没有完全坏掉……只是有点烦人。

【讨论】：