Support for global scaladoc macro definitions

[scabug]

I keep finding that I'm defining the same Scaladoc macros at the beginning of each class/object/trait definition. For instance, I like to use a macro for the name of the project that puts the name in italics and links to the project's web-site.

@define MYPROJECT ''[[http://myproject.org/ My Project]]''

This macro ensures consistent formatting, eliminates the risk of URL typos (if I defined it right), and avoids a lot of typing.

But I would like to avoid a lot more typing: specifically, the definition of that macro hundreds of times (which creates a maintenance chore if I need to modify my project's name or URL, and which increases the risk that I will define it incorrectly in some instances).

An obvious solution would be to allow Scaladoc macros to be defined with a global scope. For example, if I specified the $MYPROJECT macro definition in the root package object for a whole library, then all elements belonging to the library would inherit that macro definition and I would only need to type its definition in once!

Alternatively, or additionally, it would be nice to be able to define macros on the Scaladoc command line, that would also be applied globally to all generated Scaladocs. This would be particularly useful if it was necessary to tailor or configure the Scaladoc for a particular application or build.

Would this be possible?

[scabug]

Imported From: https://issues.scala-lang.org/browse/SI-7835?orig=1 Reporter: Mike Allen (mja)

[scabug]

Christian Krause (wookietreiber) said: I would find this very useful, too.

[scabug]

Christian Krause (wookietreiber) said: What I currently do to work around this issue is to define a documentation template trait, e.g.:

package org.my.parent

package object child {
  /**
    * @define foo bar
    */
  private[child] trait DocDummy
}

This works surprisingly well, but has some drawbacks:

• DocDummy must be mixed in explicitly wherever needed, which is usually all over the place, since this is the reason the definitions need to exist in a central location in the first place
• in the example above the trait is package private, so users can not see it directly in the API, however it still appears in the heading everywhere it is used, e.g. object Child extends Parent with DocDummy which might be confusing

But this approach also has some advantages:

• you can make the trait public for others to use and ...
• the users of your API can also use this trait in different packages, not just subpackages of the package where you make the definitions

[scabug]

Jonathan Brachthäuser (b-studios) said: Please note that [https://wiki.scala-lang.org/display/SW/Tags+and+Annotations] still claims that macro definitions on packages are supported. I was surprised to see that this is not the case as witnessed by this issue.

[unkarjedy]

Somehow similar issue in IntelliJ Scala Plugin: https://youtrack.jetbrains.com/issue/SCL-20122 (see the comment)

From https://docs.scala-lang.org/overviews/scaladoc/for-library-authors.html#macros

@define <name> <definition> allows use of $name in other Scaladoc comments within the same source file which will be expanded to the contents of

[som-snytt]

While fixing Scaladoc errors in the Scala 2 project recently, I noticed that some errors were due to the source file limitation. The naive expectation is that the macro definition is "inherited" from a parent class in a different source file.

[unkarjedy]

Looks like the specification implies that macro can be used in unrelated classes in the same file. There is nothing about inheritance. So you do not even need to inherit from some base class to use some macro in the same file.

Though, from my POV that would be quite a strange behavior. Maybe the spec wording should be refined?