scala - Scaladoc [use case]

Question

Why do some method descriptions in Scaladoc start with [use case]?

Example: scala.collection.immutable.StringOps.++

Is it just a placeholder to be replaced in the future?

Answer 1

They are simplified examples of how these methods are called. Usually these methods (++, map, flatMap, etc.) contain an implicit parameter, most often an argument called a builder factory which (simply put) abstracts creation of resulting collections.

In most cases, a client of a collection does not specify these implicit parameters, so ScalaDoc allows defining a simplified description of the method - a use case. This enables users to quickly pick up the idea behind the method in question, and not be bothered with what e.g. CanBuildFrom means and how it's used.

For example, this is the full declaration of ++:

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

In most cases, the target collection type is the same as the receiver of the call, so the call pretty much looks as if the declaration is the following (assuming ++ is defined on a, say, List):

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

Above, the implicit is resolved at compile time, and the type parameters are inferred. In most cases, this should be the client's view of the method.

And if you want to annotate your own method with use cases, use the @usecase tag in your doc comments:

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