Why are scaladoc method signatures wrong?

Question

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?

Answer 1

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]
  

Similar questions

• Why does the scaladoc say HashMap.toArray returns Array[A] instead of Array[(A,B)]?
• The List :: method and covariance ... why do they hide the real signature?
• scaladoc for map on Map ... is the documentation wrong, or am I missing something?
• What's going on here with scala.collection.immutable.Stack.+: (prepend)? ...
• Why do some method descriptions in Scaladoc start with [use case]?
• How to explain Map.map result