SI-7376 Additional trivial Scaladoc format corrections

Horizontal rule is ---- not ==== (which means header).

Sample dollars must be escaped.
SI-7376 Bad doc variable error is positioned at the variable.

For a bad $variable, the caret is positioned at the variable
in the doc instead of at the symbol being documented.