SI-7376 Scaladoc warns when discarding local doc comments with API tags

Double-star doc comments in non-dockable positions at the end of a block
will emit a warning only if API tags like @author are present, or under
-Xlint.

A real comment parser is applied early to probe for tags, to minimize
ad hoc testing or duplication, but warnings are suppressed. Residual
ad hockiness lies in precisely which tags to warn on.  Ad hoc or ad doc.

This fix is a stop gap; a richer solution would also report about other
doc locations that won't be processed.
SI-7376 Unmoored doc has correct position

The unmoored DocComment is created more eagerly so that its position
is correct despite subsequent line comments. (Previously, skipComment
would advance docPos.)

It looks like the error caret is still off by one when a doc comment
shows up in the middle of an operator, and who doesn't scaladoc the
interior of expressions?

Another bug fixed by Paul's refactor is that additional comments
between the doc and the entity no longer breaks the scaladoc.
Test added.
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.
Merge pull request #2396 from som-snytt/issue/unmoored-doc

SI-7376 Scaladoc warns when discarding local doc comments with API tags