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?

Answers


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

Need Your Help

Can Someone explain me how this NASM Program works?

assembly

This is the code i copied from a Stackoverflow.com's Question:

Want to split strings when they change case

python regex string python-3.x

I am trying to split a string when it switches from lower case to upper case inside a word.

About UNIX Resources Network

Original, collect and organize Developers related documents, information and materials, contains jQuery, Html, CSS, MySQL, .NET, ASP.NET, SQL, objective-c, iPhone, Ruby on Rails, C, SQL Server, Ruby, Arrays, Regex, ASP.NET MVC, WPF, XML, Ajax, DataBase, and so on.