Scaladoc [use case]

Question

Почему некоторые описания методов в Scaladoc начинаются с [use case]?

Пример: scala.collection.immutable.StringOps.++

Является ли это просто заполнитель должен быть заменен в будущем?

Answer 1

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

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

Например, это полная декларация ++:

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

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

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

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

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

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