How to disambiguate links to methods in scaladoc?

问题:

I'm documenting a Scala class with overloaded methods. How can I distinguish them when referring to them in scaladoc comments? For example, if I have

/**
 * 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;
}

and run sbt doc I get

Doc.scala:1: warning: The link target "Doc.foo" is ambiguous. Several (possibly overloaded) members fit the target:

• method foo[A,B>:A](x:A):B in object Doc [chosen]
• method foo[A]:Nothing in object Doc

Using foo[A,B >: A] etc. to the link doesn't work.

回答1:

The following seems do the trick in Scala 2.10.

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

And here is some hint scaladoc gives me:

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

回答2:

I found a solution (apparently the unique solution) for complex signatures, by studying the doc of scaladoc.

• Don't use space in the signature
• Use the arguments name
• For argument types as well as return types, prefix all dots with a single backslash \
• Use the star * at the end of the signature
• Use the complete signature (as the ambiguous signatures are proposed to you). This step is optional, you may be able to stop the signature earlier, as long as you finish it with *

Example:

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

回答3:

I'm still surprised at how difficult it is to get this working and the lack of documentation for scaladoc itself. I decided to search the scala code base itself in hope of some useful examples. The best ones that I found were in https://github.com/scala/scala/blob/2.12.x/test/scaladoc/resources/links.scala. Hopefully this is useful for someone else who comes across this.