The API Docs for BigDecimal introduce the meaning of scale. The current verbiage can be misleading when presenting the meaning of a scale value that's negative.

The ambiguity is in this sentence:

    If negative, the unscaled value of the number is ...

which could be replaced with the slightly more verbose:

    If the scale is negative, the unscaled value of the number is ...

To keep symmetry, also revise the positive case from:

    If zero or positive, the scale is the number of digits ...

to:

    If the scale is zero or positive, the scale is the number of digits ...