Imported From: https://issues.scala-lang.org/browse/SI-3834?orig=1
Reporter: @lrytz

@dubochet said:
There are quite a few problems here, and they are really tricky to fix.

The first problem is that B in this example actually refers to different symbols: that in (A, B) refers to the value type of the map, whilst that in => B refers to the method's type parameter, so that the signature really should be read as:

map [X] (f: ((A, B)) ⇒ X) : Map[X]

This problem is an internal Scaladoc problem. It is not specific to use cases: in fact, the exact same problem appears with the full signature for that method. I don't know how to fix it best. Most likely, it requires a mechanism whereby a type that is transformed using "as seen from" (to adapt it to the local context) should be somehow checked to make sure that the same name does not refer to different symbols at that point.

The second problem is specific to use cases. Map[X] is obviously a wrong type as Map takes two type parameters. Method map is inherited from TraversableLike, where the return type of the use case is defined as $$Coll[B] (the variable representing the current collection, with elements of type B). In TraversableLike, this looks fine because most of its subclasses are collections that only take a single type parameter. But Map is an exception, and there is no mechanism to change the expansion of $$Coll when the number of parameters changes. A solution would be to override map in Map so as to refine the use case, but that would introduce a refinement only to satisfy documentation. Maybe Scaladoc should allow overriding documentation separately from overriding actual members.

@odersky said:
Note that it's easy to override documentation without overriding actual members: Just put in an abstract type signature with the new documentation. I do not see how this is a problem specific to use cases, though. Reassigning to Aleks.

@paulp said:
In case anyone can tell me what I'm doing wrong or whether this indicates that the suggested approach does not work, here is what I added to collection.MapLike without seeing any change in the generated documentation.

  
  /** Builds a new collection by applying a function to all elements of this $$coll.
   *
   *  @param f      the function to apply to each element.
   *  @tparam C     the element type of the returned collection.
   *  @tparam That  $$thatinfo
   *  @param bf     $$bfinfo
   *  @return       a new collection of type `That` resulting from applying the given function
   *                `f` to each element of this $$coll and collecting the results.
   *
   *  @usecase  def map[C, That](f: ((A, B)) => C): That
   *  
   *  @return       a new $$coll resulting from applying the given function
   *                `f` to each element of this $$coll and collecting the results.
   */
  def map[C, That](f: ((A, B)) => C)(implicit bf: CanBuildFrom[This, C, That]): That

@VladUreche said (edited on Mar 20, 2012 2:29:27 PM UTC):
Does adding multiple usecases to the map method solve the problem?

/** ...
 *  @usecase map [B] (f: ((A, B)) ⇒ B) : $IterableColl[B]
 *  @usecase map [B,C,D] (f: ((A, B)) ⇒ (C, D)) : $Coll[C, D]
 */
def map [B, That] (f: ((A, B)) ⇒ B)(implicit bf: CanBuildFrom[Map[A, B], B, That]): That 

If so, I will get the usecase overriding to work and we can assign the bug to the library folks :)

@VladUreche said:
Please reopen if multiple usecases won't do the trick.