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:
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);
}
Solution
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.