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?

Teakettle

I actually just noticed the rationale behind this tag, described in the comments of the accepted answer: #1723226 – Teakettle

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]
 */

Aurora

I want a 'use case' hiding button. – Dehaven

That's probably a good idea. Perhaps you could submit a request for enhancement at the scala trac site. – Aurora

I've only noticied who you are right now. So, answering your suggestion: actually I should commit it myself. Here is the only brazillian guy that has attended to Scaladays 2010, and back then I was the sole Scaladoc2 contributor. Nice to hear from you, cheers. – Dehaven

Yeah, I know, I keep seeing you in the ScalaDoc related commits. Cheers! – Aurora

i would like a non-use case hiding button. In most cases people look these things up to use them, not to override them. – Ancilla