math/big: SetMantExp doc comment unclear

[darkfeline]

https://cs.opensource.google/go/go/+/master:src/math/big/float.go;l=309

Hopefully I'm not having a moment of stupidity, but the example for SetMantExp doesn't make sense to me:

// SetMantExp sets z to mant × 2**exp and returns z.
// The result z has the same precision and rounding mode
// as mant. SetMantExp is an inverse of MantExp but does
// not require 0.5 <= |mant| < 1.0. Specifically:
//
//	mant := new(Float)
//	new(Float).SetMantExp(mant, x.MantExp(mant)).Cmp(x) == 0

What is x here? I assume that it is an arbitrary *Float, although it would be good if that were stated explicitly.

This is saying that

mant := new(Float)
new(Float).SetMantExp(mant, x.MantExp(mant))

is equal to x (.Cmp(x) == 0).

new(Float).SetMantExp(mant, x.MantExp(mant)) looks like it should be a zero *Float since mant is a zero *Float. The exponent is set to the same as x (and mant is set to the mantissa of x although not used later) but that does not matter since the mantissa is zero. Based off my algebra skills from a long time ago, x should be a zero *Float then, to satisfy this example.

What exactly is this example supposed to demonstrate? If it is just demonstrating using a mantissa outside of [0.5, 1), I can think of many clearer examples.

[robpike]

What it's saying is that for any x, you can deconstruct it with MantExp and reconstruct it with SetMantExp. The call to MantExp will happen first, setting Mant to the mantissa of x and returning the exponent. The arguments to SetMantExp are therefore the mantissa and exponent of x, so the call recreates x, stores it in the new Float, and Cmp returns 0.

I didn't know this until I read the documentation. It's concise but accurate. It probably needs a phrase such as "given x".

[darkfeline]

Ah right, because mant is a pointer. I don't encounter this pattern often (where a pointer argument in a call expression gets mutated by a succeeding expression argument). Ignoring my failure of code comprehension, I think adding some explanatory text would be helpful, e.g., "To reconstruct a Float from the results of a MantExp call, one could do:".

Actually, is this example useful? It isn't particularly difficult to see how one might pass in the results of MantExp to SetMantExp

[gopherbot]

Change https://golang.org/cl/344249 mentions this issue: math/big: clarified doc string for SetMantExp