Как устранить неоднозначность ссылок на методы в scaladoc?

Question

Я документирую класс Scala с перегруженными методами. Как я могу отличить их при обращении к ним в комментариях скаляр? Например, если у меня есть

/**
 * 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: warning: Цель ссылки "Doc.foo" неоднозначна. Несколько (возможно, перегруженных) членов соответствуют цели:

• метод foo[A,B>:A](x:A):B в объекте Док [выбрано]
• метод foo[A]:Nothing в объекте док

С помощью foo[A,B >: A] и т.д. по ссылке не работает.

Answer 1

Следующее, кажется, делает трюк в Scala 2.10.

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

И вот какой-то намек скаладок дает мне:

[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. Я решил поискать саму базу кода Scala в надежде на несколько полезных примеров. Лучшие из найденных мною были в https://github.com/scala/scala/blob/2.12.x/test/scaladoc/resources/links.scala. Надеюсь, это полезно для кого-то, кто сталкивается с этим.

Answer 4

Я нашел решение (по-видимому, уникальное решение) для сложных сигнатур, изучая документ скальдока.

• Не используйте пробел в подписи
• Используйте имя аргумента
• Для типов аргументов, а также для типов возврата, ставьте перед всеми точками одну обратную косую черту \
• Использовать звезду * в конце подписи
• Используйте полную подпись (так как вам предлагаются неоднозначные подписи). Этот шаг не является обязательным, вы можете остановить подпись раньше, если вы закончите с *

Пример:

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