SI-7080 improve boundary value checking for BitSet

When BitSet accepts a very large integer such as Int.MaxValue,
integer overflow possibly occurs in the calculation of boundary
value "nwords * WordLength". This faulty boundary condition
causes empty-iterator problem like following:

scala> import collection.mutable.BitSet
import collection.mutable.BitSet

scala> val x = BitSet(Int.MaxValue)
x: scala.collection.mutable.BitSet = BitSet()

scala> x.iterator
res0: Iterator[Int] = empty iterator
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.
Change unrecognized scaladoc comments to C-style
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.
SI-7324 jvm not cool with 255+ parameters

Fail those monster methods rather than generating bad bytecode.
Fixed BigDecimal documentation for primitive conversion methods.
Merge pull request #2427 from aldenml/bigdecimal-doc-fix

Fix BigDecimal documentation for primitive conversion methods.
Merge pull request #2426 from paulp/pr/7324

SI-7324 jvm not cool with 255+ parameters
Merge pull request #2398 from huitseeker/silence_scaladoc_better

Change unrecognized scaladoc comments to C-style
Merge pull request #2360 from ihji/bugfix/SI-7080

SI-7080 improve boundary value checking for BitSet
Merge pull request #2396 from som-snytt/issue/unmoored-doc

SI-7376 Scaladoc warns when discarding local doc comments with API tags
AbstractFile.getDirectory does not return null when outDir is "."