Defining scaladoc macros for reuse in companion object

Question

I am trying to understand how scaladoc macros work. E.g.

/** $DESCR
  *
  * @define DESCR
  * A `Consumer` simplifies resource management...
  *
  * @define KEY
  * the key type
  *
  * @define VALUE
  * the value type
  */
object Consumer {
  /** Creates a new consumer
    *
    * @tparam A       $KEY
    * @tparam B       $VALUE
    */
  def apply[A, B](): Consumer[A, B] = ???
}

/** $DESCR
  *
  * @tparam A $KEY
  * @tparam B $VALUE
  */
trait Consumer[-A, +B]

I was under the impression that this should produce a documentation which has both for trait and companion object the description A Consumer simplifies resource management..., and also shows the two type parameter descriptions in the apply method and the trait.

But the macros seem to be unavailable in the trait. While the object is correctly documented, the trait doc just shows the macro names $DESCR, $KEY, $VALUE.