Scaladoc [прецедент]

Ответ 1

Это упрощенные примеры того, как эти методы вызывают. Обычно эти методы (++, map, flatMap и т.д.) Содержат неявный параметр, чаще всего аргумент, называемый построителем factory, который (просто ставит) реферат создает результирующие коллекции.

В большинстве случаев клиент коллекции не задает эти неявные параметры, поэтому ScalaDoc позволяет определить упрощенное описание метода - вариант использования. Это позволяет пользователям быстро подобрать идею, лежащую в основе рассматриваемого метода, и не беспокоиться о том, что, например, CanBuildFrom означает и как он используется.

Например, это полное объявление ++:

def ++[B >: A, That](that: TraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That

В большинстве случаев целевой тип собирания совпадает с получателем вызова, поэтому вызов в значительной степени выглядит так, как если бы объявление было следующим (предполагая, что ++ определено на a, скажем, List)

def ++(that: TraversableOnce[A]): List[A]

Выше, неявный разрешается во время компиляции, и параметры типа выводятся. В большинстве случаев это должен быть вид клиента для метода.

И если вы хотите аннотировать свой собственный метод в случаях использования, используйте тег @usecase в комментариях к вашему документу:

/** ...
 *  ...
 *  @usecase def ++(that: TraversableOnce[A]): List[A]
 */