Why are scaladoc method signatures wrong?

There are a lot of places in the Scala API, particularly in collections, where method signatures are wrong.

For example, the scaladoc signature for Map.flatMap says

def flatMap[B](f: (A) ⇒ GenTraversableOnce[B]): Map[B]

But the actual signature is

flatMap[B, That](f: ((A, B)) ⇒ GenTraversableOnce[B])
    (implicit bf: CanBuildFrom[Map[A, B], B, That]): That

This one especially makes no sense because the scaladoc signature includes Map[B], but Map has two type parameters, not one.

What's going on here? Is this a mistake?

Chris Martin

The incorrect signatures you're see in the generated documentation are called "use cases". They're supposed to clarify the documentation by showing idealized API, similar to the real one but omitting tedious details (like the pervasive implicit CanBuildFrom parameter which bothers some people).

For methods with use cases, you can get to the real signature by clicking the method name to show the details for that method, and then clicking "Full Signature" to expand another section that shows the signature.

References

Scala issue SI-3448, created May 2010, deals specifically with the wrong number of type parameters being shown for Map. This issue as closed "Won't Fix" in July 2012.
Paul Phillips' talk Scala Collections: Why Not? from January 2014 scorns the use cases as "lies" in slide 1, slide 2, slide 3.
In GenTraversableLike.scala you can see an example of a directive which causes use case documentation to be generated:
```
@usecase def flatMap[B](f: A => TraversableOnce[B]): $Coll[B]
```

Why are scaladoc method signatures wrong?

References

Similar questions