Ответ 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]
*/