Misleading type signatures in scaladoc for Map classes

[scabug]

ScalaDoc is suggesting the type for foldLeft is,

foldLeft[B](z: B)(op: (B, (A, B)) ⇒ B): B

which is of course wrong and very misleading. It looks like there is a systematic error in doing a naive text substitution without doing proper variable capture. This leads to the B's being confused in this example. folding would be rather less useful were its return type bound to the value type in the Map.

[scabug]

Imported From: https://issues.scala-lang.org/browse/SI-6947?orig=1
Reporter: Declan Conlon (dconlon)
Other Milestones: 2.13.0-M1
See #9430

[scabug]

@szeiger said:
This problem is a lot more pervasive. Lots of inherited methods have a type parameter B which is indistinguishable from Map's own B in the docs.

I think the nicest solution, at least for Map, would be to rename the type parameters from A, B to K, V.

[scabug]

@szeiger said:
PR: scala/scala#5265

[scabug]

@szeiger said:
Reopening because use case signatures are still wrong. There is no automatic substitution of type parameters for these because the signatures are not real anyway, so we cannot reliably substitute anything. I expect we will have to duplicate all affected scaladoc comments from TraversableLike in MapLike in order to fix this.

[scabug]

@szeiger said:
After taking a closer look, it seems that substitutions are performed, and indeed many use case signatures look correct. The problem with some signatures is that substitution of the collection subtype leads to types like "GenMap" being substituted for "TraversableOnce", so you end up with "GenMap[B]". I didn't continue this investigation to find out why it doesn't substitute further to "GenMap[(K, V)]" like it does in other places because it is wrong either way. GenMap takes two type parameters.

[scabug]

@szeiger said:
I'm throwing the towel. Here's what I have to far: https://github.com/scala/scala/compare/2.12.x...szeiger:wip/map-scaladocs?expand=1

This only scratches the tip of the iceberg. Many interesting subclasses inherit the wrong comments and in many cases cannot be
fixed due to the way in which comments are inherited. The ones that could be fixed would require huge amounts of duplication.

In the end the problem with the scaladoc comments is the same as with nonsensical methods and slow implementations: Adding lots of stuff high up in the inheritance hierarchy means you end up with lots of stuff that doesn't really work.

[buzden]

Short signature of the map() method of the Map class is also incorrect:

• it says that this method returns Map[B] which is improssible due to Map has two type parameters;
• it has wrong argument signature due to (K, V) is given as an argument for the argument-function instead of simply A.

[SethTisue]

when https://github.com/scala/collection-strawman replaces the old collections in Scala 2.13 we could take a fresh look at this

[julienrf]

This is what we now get for foldLeft in Map:

I’ve checked all the places where we use @usecase and saw no misleading type signature. I think we can close this issue.

[julienrf]

(And this is also what we get for the map operation)