math/big: clarify addVW and subVW preconditions

[josharian]

I'm working on an arm64 math/big implementation.

The docs for addVW (arith.go) say:

// Argument y must be either 0 or 1.
func addVW_g(z, x []Word, y Word) (c Word)

But e.g. running TestFloatSetPrec sends in many values for y. The existing implementations handle them correctly. I care because my initial arm64 implementation transfers y directly to the carry flag at the start, which only works if y is 0 or 1.

subVW does not say that y must be either 0 or 1, but in practice it appears to be, and the semantics are less clear if it is not. However, TestFunVW appears to intentionally send in y=2 to confirm that there's no bad behavior when z and x are nil.

What preconditions do addVW and subVW actually have?

@griesemer feel free to clarify here or just send a CL.

(Additional docs in general in arith.go would be awesome. Right now I'm inferring shlVU and friends from the existing code.)

[griesemer]

addVW originally was expected to only consume 0 and 1, but it's used at least in one place for other values (float.go:496).

subVW may only receive 0 and 1 but for the tests, but I believe the Go and assembly code (x86) can handle arbitrary words. It's not hard.

Suggested course of action:

• Adjust doc strings; perhaps add extra tests.
• If it's hugely faster to just have to deal with 0 and 1, perhaps special case in the assembly routine with a test. This is not where the time goes.