Scaladoc [caso de uso]

Question

¿Por qué algunas descripciones de métodos en Scaladoc comienzan con [use case]?

Ejemplo: scala.collection.immutable.StringOps.++

¿Es sólo un marcador de posición para ser reemplazado en el futuro?

Answer 1

Son ejemplos simplificados de cómo se llaman estos métodos. Por lo general, estos métodos (++, map, flatMap, etc.) contienen un parámetro implícito, muy a menudo un argumento llamado fábrica de creación que (simplemente) resuma la creación de las colecciones resultantes.

En la mayoría de los casos, un cliente de una colección no especifica estos parámetros implícitos, por lo que ScalaDoc permite definir una descripción simplificada del método: un caso de uso . Esto permite a los usuarios recoger rápidamente la idea detrás del método en cuestión, y no molestarse con lo que p. CanBuildFrom significa y cómo se usa.

Por ejemplo, esta es la declaración completa de ++:

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

En la mayoría de los casos, el tipo de colección de destino es el mismo que el receptor de la llamada, por lo que la llamada casi parece como si la declaración es la siguiente (suponiendo ++ se define en una, digamos, List):

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

arriba, lo implícito se resuelve en tiempo de compilación, y los parámetros de tipo son inferidos. En la mayoría de los casos, esta debería ser la vista del método por parte del cliente.

Y si desea anotar su propio método con casos de uso, utilice la etiqueta @usecase en sus doc comentarios:

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