Imported From: https://issues.scala-lang.org/browse/SI-9785?orig=1
Reporter: Tillmann Rendel (toxaris)
Attachments:

• inherited.png (created on May 18, 2016 9:36:22 PM UTC, 35791 bytes)
• MapLike.png (created on May 18, 2016 10:10:50 PM UTC, 83203 bytes)

Tillmann Rendel (toxaris) said:
I noted that this bug also affects the documentation of the standard library. The first example I found is the following:

scala.collection.IterableLike uses a macro in the documentation of toIterable:

/** A template trait for iterable collections of type `Iterable[A]`.
 *   ...
 *  @define coll iterable collection
 */
trait IterableLike[+A, +Repr] extends ... {
  ...
  /** Returns this $coll as an iterable collection.
   *  ...
   */
  override /*TraversableLike*/ def toIterable: Iterable[A] =
    thisCollection
  ...
}

In MapLike, the macro is redefined:

/** A template trait for maps, which associate keys with values.
 *  ...
 *  @define coll map
 *  ...
 */
trait MapLike[A, +B, +This <: ...] extends ...
    with IterableLike[(A, B), This] with ... {
  ...
}

And toIterable is simply inherited from IterableLike (not overriden).

I think the documentation for MapLike.toIterable is supposed to read "Returns this map as an iterable collection." Instead, it reads "Returns this iterable collection as an iterable collection." (Emphasis mine in both cases).

This happens because ScalaDoc fails to re-substitute the macro $coll when inheriting the documentation for toIterable.

I don't know whether this only affects such stylistic issues or whether some of the more substantial macros in the standard library documentation are also instantiated wrongly.

!MapLike.png|thumbnail!

The screenshot shows how the documentation of different methods uses different language to refer to the "this map":

• toArray and toBuffer use "this map"
• toIndexedSeq uses "this traversable or iterator"
• toIterable and toIterator use "this iterable collection"

I think that "this map" should be uses consistently, and that this bug disables the documentation macro machinery that is supposed to achieve this consistency.

@janekdb Is this something that someone without a lot experience in compilers can tackle?

@Lasering absolutely, yes!

this could be a good ticket to tackle if you want to get your feet wet, at least a little, with compiler internals. most tickets labeled "scaladocs tool" are like that. and a great deal of scalac/scaladoc-tool work doesn't require training/experience in compilers. https://www.scaladays.org/2018/new-york/schedule/you-are-a-scala-contributor has some recommendations on reading/videos to start with, beginning with https://docs.scala-lang.org/overviews/reflection/symbols-trees-types.html

but if exposure to scalac internals isn't appealing to you, pick a different ticket :-)

@SethTisue I found and solved the problem.

Lasering/scala@2c5b873

I can make the PR.