Scaladoc [cas d'utilisation]

Question

Pourquoi certaines descriptions de méthodes dans Scaladoc commencent-elles par [use case]?

Exemple: scala.collection.immutable.StringOps.++

Est-ce juste un espace réservé à remplacer à l'avenir?

Answer 1

Ce sont des exemples simplifiés de la façon dont ces méthodes sont appelées. Habituellement, ces méthodes (++, map, flatMap, etc.) contiennent un paramètre implicite, le plus souvent un argument appelé une usine de construction qui (simplement) résume la création de collections résultantes.

Dans la plupart des cas, un client d'une collection ne spécifie pas ces paramètres implicites. ScalaDoc permet donc de définir une description simplifiée de la méthode: , cas d'utilisation. Cela permet aux utilisateurs de saisir rapidement l'idée derrière la méthode en question, et de ne pas être dérangé par quoi, par exemple. CanBuildFrom signifie et comment il est utilisé.

Par exemple, ceci est la déclaration complète de ++:

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

Dans la plupart des cas, le type de collecte cible est le même que le récepteur de l'appel, de sorte que l'appel à peu près semble que la déclaration est la suivante (en supposant ++ est défini sur, disons, List):

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

au-dessus, l'implicite est résolu au moment de la compilation, et les paramètres de type sont inférées. Dans la plupart des cas, cela devrait être l'opinion du client sur la méthode.

Et si vous voulez annoter votre propre méthode avec les cas d'utilisation, utilisez la balise @usecase dans vos commentaires doc:

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