How to disambiguate links to methods in scaladoc?

Question

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         


        

Answer 1

What I found very usefull in IntelliJ is right clicking on a method you would like to put in [[ ]] and choosing "Copy reference".

Steps:

1. You find a method you'd like to reference somewhere else.

2. You right click on the method name and choose "Copy reference".

3. You paste it in [[ ]] in your documentation (and write a label of your choice next to it, e.g. "apply(String)").

4. Voilà.

Answer 2

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.

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

Answer 4

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