Verbatim code in scaladoc

Question

I have a Color companion object which holds a few useful colors, and I'd like to document them in the following manner:

object Color {
  /** (.3, .3, .3, 1) */
  val darkGrey = Color(.3, .3, .3, 1);
}

As you have probably noticed, all I want is for the string (.3, .3, .3, 1) to show up right below val darkGrey in the documentation for Color. The problem is that Scaladoc takes everything before the first period to be a sentence, and everything after that before is hidden "inside" the expandable arrow. So what I get is something like this:

enter image description here

which is clearly undesirable. Ideally, either the entire string would be shown or the entire string would be hidden. Is there a way to achieve either of these?

I've also tried the two following methods, and none of them work.

object Color {
  /**
    * (.3, .3, .3, 1)
    */
  val darkGrey = Color(.3, .3, .3, 1);
}
object Color {
  /** {{{
    * (.3, .3, .3, 1)
    * }}}
    */
  val darkGrey = Color(.3, .3, .3, 1);
}   
object Color {
  /** ` (.3, .3, .3, 1) ` */
  val darkGrey = Color(.3, .3, .3, 1);
}

score 5 · Accepted Answer · answered Jun 19 '12 at 00:41

It seems the period detection is in a late stage of scaladoc, it doesn't matter how it's generated or escaped. The only solution I found is a bit wacky -- you need to avoid the period. Use a different unicode:

/** @define dot \u2024 */
object Color {
  /** `(${dot}3, ${dot}3, ${dot}3, 1)` */
  val darkGrey = Color(.3, .3, .3, 1);
}
case class Color(r:Double,g:Double,b:Double,alpha:Double)

If you save your source code in UTF-8, I guess you can also directly paste the alternative period character.

Verbatim code in scaladoc

1 Answers1