Scaladoc [przypadek użycia]

Question

Dlaczego niektóre opisy metod w Scaladoc zaczynają się od [use case]?

Przykład: scala.collection.immutable.StringOps.++

Czy to tylko zastępczy zostać zastąpiony w przyszłości?

Answer 1

Są to uproszczone przykłady sposobu wywoływania tych metod. Zwykle te metody (++, , , , flatMap itd.) Zawierają niejawny parametr, najczęściej jest to argument zwany fabryką budowniczych, który (po prostu) streszcza tworzenie wynikowych kolekcji.

W większości przypadków klient kolekcji nie określa tych niejawnych parametrów, więc ScalaDoc pozwala na zdefiniowanie uproszczonego opisu metody - a mianowicie przypadek użycia. Dzięki temu użytkownicy mogą szybko zorientować się w idei danej metody i nie przejmować się, np. CanBuildFrom oznacza i jak jest używany.

Na przykład, jest to pełna deklaracja ++:

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

W większości przypadków typ kolekcja cel jest taki sam jak w odbiorniku zaproszenia, więc wywołanie dość dużo wygląda jakby deklaracja jest następujący (zakładając ++ jest zdefiniowana na a, powiedzmy, List):

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

Powyżej niejawny został rozwiązany w czasie kompilacji, a parametry są typu wywnioskować. W większości przypadków powinno to być spojrzenie klienta na tę metodę.

A jeśli chcesz opisywanie własną metodę z przypadków użycia, należy użyć znacznika @usecase w swoich komentarzach Doc:

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