¿Cómo desambiguar los enlaces a los métodos en scaladoc?

scala-2.10 method-names

Question

Estoy documentando una clase Scala con métodos sobrecargados . ¿Cómo puedo distinguirlos cuando me refiero a ellos en comentarios scaladoc? Por ejemplo, si tengo

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

y ejecute sbt doc obtengo

Doc.scala: 1: advertencia: el destino del enlace "Doc.foo" es ambiguo. Varios miembros (posiblemente sobrecargados) se ajustan al objetivo:

• Método foo[A,B>:A](x:A):B en el objeto Doc [elegido]
• Método foo[A]:Nothing en el objeto Doc.

Usar foo[A,B >: A] etc. para el enlace no funciona.

Answer 1

Encontré una solución (aparentemente la única solución) para firmas complejas, al estudiar el documento de scaladoc.

• No uses espacio en la firma.
• Usa el nombre de los argumentos.
• Para los tipos de argumentos y los tipos de retorno, prefija todos los puntos con una sola barra invertida /
• Usa la estrella * al final de la firma.
• Use la firma completa (ya que se le proponen firmas ambiguas). Este paso es opcional, puede detener la firma antes, siempre que la termine con *

Ejemplo:

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 2

Lo siguiente parece hacer el truco en Scala 2.10.

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

Y aquí hay una pista que Scaladoc me da:

[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

Todavía me sorprende lo difícil que es conseguir que esto funcione y la falta de documentación para scaladoc en sí. Decidí buscar el código base de Scala con la esperanza de algunos ejemplos útiles. Los mejores que encontré estaban en https://github.com/scala/scala/blob/2.12.x/test/scaladoc/resources/links.scala . Esperemos que esto sea útil para alguien que se encuentre con esto.