New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
ScalaDoc fails to re-substitute macros for inherited members #9785
Comments
Imported From: https://issues.scala-lang.org/browse/SI-9785?orig=1
|
Tillmann Rendel (toxaris) said: 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":
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. I can make the PR. |
Problem
ScalaDoc should expand redefined macros in documentation for inherited members to the macro bodies from the subclass, but expands the redefined macros to their old bodies from the superclass instead.
Background
According to https://wiki.scala-lang.org/display/SW/Tags+and+Annotations, documentation inheritance and ScalaDoc macros should interact as follows (emphasis mine):
{quote}If a comment containing macros is inherited, macros will normally be extended to the bodies defined in the super-class. However, It is possible to redefine macros in the sub-class (using @define tags with the same names) such that macros in inherited comments are extended to the redefined bodies. This happens even if members are inherited, as opposed to being overridden or implemented.{quote}
Contrary to this description, Scaladoc only expands macros to their redefined bodies if members are overriden or implemented, but not if members are merely inherited.
Example
Expected Behavior
In the documentation of Sub, all three methods should be documented with "Sub".
Actual Behavior
In the documentation of Sub, only overriden and implemented (the methods that show up in the body of Sub) are documented with "Sub", but inherited (the method that is only inherited) is documented with "Super".
Screenshot of Actual Behavior
!inherited.png|thumbnail!
The text was updated successfully, but these errors were encountered: