math/big: more documentation

Good enough for now.

Fixes #11241.

Change-Id: Ieb50809f104d20bcbe14daecac503f72486bec92
Reviewed-on: https://go-review.googlesource.com/15111Reviewed-by: Alan Donovan <adonovan@google.com>

src/math/big/doc.go

@@ -10,25 +10,42 @@ The following numeric types are supported:
 	Rat    rational numbers
 	Float  floating-point numbers
 
-Declaration: The zero value for an Int, Rat, or Float (not the pointers
-*Int, *Rat, *Float!) correspond to 0. Thus, new values can be declared
-in the usual ways and denote 0 without further initialization:
+The zero value for an Int, Rat, or Float correspond to 0. Thus, new
+values can be declared in the usual ways and denote 0 without further
+initialization:
 
 	var x Int        // &x is an *Int of value 0
 	var r = &Rat{}   // r is a *Rat of value 0
 	y := new(Float)  // y is a *Float of value 0
 
-Arithmetic: Setters, numeric operations and predicates are represented
-as methods of the form:
+Alternatively, new values can be allocated and initialized with factory
+functions of the form:
+
+	func NewT(v V) *T
+
+For instance, NewInt(x) returns an *Int set to the value of the int64
+argument x, NewRat(a, b) returns a *Rat set to the fraction a/b where
+a and b are int64 values, and NewFloat(f) returns a *Float initialized
+to the float64 argument f. More flexibility is provided with explicit
+setters, for instance:
+
+	var z1 Int
+	z1.SetUint64(123)                 // z1 := 123
+	z2 := new(Rat).SetFloat64(1.2)    // z2 := 6/5
+	z3 := new(Float).SetInt(z1)       // z3 := 123.0
+
+Setters, numeric operations and predicates are represented as methods of
+the form:
 
 	func (z *T) SetV(v V) *T          // z = v
 	func (z *T) Unary(x *T) *T        // z = unary x
 	func (z *T) Binary(x, y *T) *T    // z = x binary y
-	func (x *T) Pred() T1             // v = pred(x)
+	func (x *T) Pred() P              // p = pred(x)
 
 with T one of Int, Rat, or Float. For unary and binary operations, the
-result is the receiver (usually named z in that case); if it is one of
-the operands x or y it may be safely overwritten (and its memory reused).
+result is the receiver (usually named z in that case; see below); if it
+is one of the operands x or y it may be safely overwritten (and its memory
+reused).
 
 Arithmetic expressions are typically written as a sequence of individual
 method calls, with each call corresponding to an operation. The receiver
@@ -45,10 +62,10 @@ aliasing of parameters, so it is perfectly ok to write
 
 to accumulate values x in a sum.
 
-Rationale: By always passing in a result value via the receiver, memory
-use can be much better controlled. Instead of having to allocate new memory
-for each result, an operation can reuse the space allocated for the result
-value, and overwrite that value with the new result in the process.
+(By always passing in a result value via the receiver, memory use can be
+much better controlled. Instead of having to allocate new memory for each
+result, an operation can reuse the space allocated for the result value,
+and overwrite that value with the new result in the process.)
 
 Notational convention: Incoming method parameters (including the receiver)
 are named consistently in the API to clarify their use. Incoming operands
@@ -68,5 +85,15 @@ Int.Sign), simply return the result. In this case, the receiver is typically
 the first operand, named x:
 
 	func (x *Int) Sign() int
+
+Various methods support conversions between strings and corresponding
+numeric values, and vice versa: *Int, *Rat, and *Float values implement
+the Stringer interface for a (default) string representation of the value,
+but also provide SetString methods to initialize a value from a string in
+a variety of supported formats (see the respective SetString documentation).
+
+Finally, *Int, *Rat, and *Float satisfy the fmt package's Scanner interface
+for scanning and (except for *Rat) the Formatter interface for formatted
+printing.
 */
 package big

src/math/big/floatconv_test.go

@@ -567,7 +567,6 @@ func TestFloatFormat(t *testing.T) {
 		{"%v", -1e-9, "-1e-09"},
 		{"%v", float32(-1e-9), "-1e-09"},
 		{"%010v", 0.0, "0000000000"},
-		{"%010v", 0.0, "0000000000"},
 
 		// *Float cases
 		{"%.20f", "1e-20", "0.00000000000000000001"},

src/math/big/ftoa.go

@@ -46,6 +46,7 @@ func (x *Float) Text(format byte, prec int) string {
 }
 
 // String formats x like x.Text('g', 10).
+// (String must be called explicitly, Float.Format does not support %s verb.)
 func (x *Float) String() string {
 	return x.Text('g', 10)
 }