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?
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.
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.
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 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