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

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

/**
 * 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 в объекте Doc [selected]
  • метод foo[A]:Nothing в объекте Doc

Использование foo[A,B >: A] и т.д. для ссылки не работает.

Ответы

Ответ 1

Следующее выглядит как трюк в Scala 2.10.

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

И вот какой-то подсказку scaladoc дает мне:

[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 apply method]] and
[warn]  - [[scala.collection.immutable.List$.apply object List 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

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

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

Пример:

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

Я все еще удивляюсь тому, как сложно добиться этой работы и отсутствия документации для самого скаладока. Я решил найти базу кода scala сам в надежде на некоторые полезные примеры. Лучшие, которые я нашел, были в https://github.com/scala/scala/blob/2.12.x/test/scaladoc/resources/links.scala. Надеюсь, это полезно для кого-то, кто сталкивается с этим.