Update documentation, clean up package level documentation (shopspring#173)

* Update documentation, clean up package level documentation

Author: mwoss

README.md

@@ -4,15 +4,15 @@
 
 Arbitrary-precision fixed-point decimal numbers in go.
 
-NOTE: can "only" represent numbers with a maximum of 2^31 digits after the decimal point.
+_Note:_ Decimal library can "only" represent numbers with a maximum of 2^31 digits after the decimal point.
 
 ## Features
 
- * the zero-value is 0, and is safe to use without initialization
- * addition, subtraction, multiplication with no loss of precision
- * division with specified precision
- * database/sql serialization/deserialization
- * json and xml serialization/deserialization
+ * The zero-value is 0, and is safe to use without initialization
+ * Addition, subtraction, multiplication with no loss of precision
+ * Division with specified precision
+ * Database/sql serialization/deserialization
+ * JSON and XML serialization/deserialization
 
 ## Install
 
@@ -70,8 +70,8 @@ http://godoc.org/github.com/shopspring/decimal
 
 #### Why don't you just use float64?
 
-Because float64s (or any binary floating point type, actually) can't represent
-numbers such as 0.1 exactly.
+Because float64 (or any binary floating point type, actually) can't represent
+numbers such as `0.1` exactly.
 
 Consider this code: http://play.golang.org/p/TQBd4yJe6B You might expect that
 it prints out `10`, but it actually prints `9.999999999999831`. Over time,

decimal-go.go

@@ -8,6 +8,7 @@
 // Can do binary floating point in multiprecision decimal precisely
 // because 2 divides 10; cannot do decimal floating point
 // in multiprecision binary precisely.
+
 package decimal
 
 type decimal struct {

decimal.go

@@ -1,20 +1,19 @@
 // Package decimal implements an arbitrary precision fixed-point decimal.
 //
-// To use as part of a struct:
-//
-//     type Struct struct {
-//         Number Decimal
-//     }
-//
 // The zero-value of a Decimal is 0, as you would expect.
 //
 // The best way to create a new Decimal is to use decimal.NewFromString, ex:
 //
 //     n, err := decimal.NewFromString("-123.4567")
 //     n.String() // output: "-123.4567"
 //
-// NOTE: This can "only" represent numbers with a maximum of 2^31 digits
-// after the decimal point.
+// To use Decimal as part of a struct:
+//
+//     type Struct struct {
+//         Number Decimal
+//     }
+//
+// Note: This can "only" represent numbers with a maximum of 2^31 digits after the decimal point.
 package decimal
 
 import (
@@ -32,14 +31,14 @@ import (
 //
 // Example:
 //
-//     d1 := decimal.NewFromFloat(2).Div(decimal.NewFromFloat(3)
+//     d1 := decimal.NewFromFloat(2).Div(decimal.NewFromFloat(3))
 //     d1.String() // output: "0.6666666666666667"
-//     d2 := decimal.NewFromFloat(2).Div(decimal.NewFromFloat(30000)
+//     d2 := decimal.NewFromFloat(2).Div(decimal.NewFromFloat(30000))
 //     d2.String() // output: "0.0000666666666667"
-//     d3 := decimal.NewFromFloat(20000).Div(decimal.NewFromFloat(3)
+//     d3 := decimal.NewFromFloat(20000).Div(decimal.NewFromFloat(3))
 //     d3.String() // output: "6666.6666666666666667"
 //     decimal.DivisionPrecision = 3
-//     d4 := decimal.NewFromFloat(2).Div(decimal.NewFromFloat(3)
+//     d4 := decimal.NewFromFloat(2).Div(decimal.NewFromFloat(3))
 //     d4.String() // output: "0.667"
 //
 var DivisionPrecision = 16
@@ -53,6 +52,7 @@ var DivisionPrecision = 16
 var MarshalJSONWithoutQuotes = false
 
 // Zero constant, to make computations faster.
+// Zero should never be compared with == or != directly, please use decimal.Equal or decimal.Cmp instead.
 var Zero = New(0, 1)
 
 var zeroInt = big.NewInt(0)
@@ -119,11 +119,13 @@ func NewFromBigInt(value *big.Int, exp int32) Decimal {
 }
 
 // NewFromString returns a new Decimal from a string representation.
+// Trailing zeroes are not trimmed.
 //
 // Example:
 //
 //     d, err := NewFromString("-123.45")
 //     d2, err := NewFromString(".0001")
+//     d3, err := NewFromString("1.47000")
 //
 func NewFromString(value string) (Decimal, error) {
 	originalInput := value
@@ -207,7 +209,7 @@ func NewFromFloat(value float64) Decimal {
 	return newFromFloat(value, math.Float64bits(value), &float64info)
 }
 
-// NewFromFloat converts a float32 to Decimal.
+// NewFromFloat32 converts a float32 to Decimal.
 //
 // The converted number will contain the number of significant digits that can be
 // represented in a float with reliable roundtrip.
@@ -767,13 +769,13 @@ func (d Decimal) StringFixed(places int32) string {
 //
 // Example:
 //
-// 	   NewFromFloat(0).StringFixed(2) // output: "0.00"
-// 	   NewFromFloat(0).StringFixed(0) // output: "0"
-// 	   NewFromFloat(5.45).StringFixed(0) // output: "5"
-// 	   NewFromFloat(5.45).StringFixed(1) // output: "5.4"
-// 	   NewFromFloat(5.45).StringFixed(2) // output: "5.45"
-// 	   NewFromFloat(5.45).StringFixed(3) // output: "5.450"
-// 	   NewFromFloat(545).StringFixed(-1) // output: "550"
+// 	   NewFromFloat(0).StringFixedBank(2) // output: "0.00"
+// 	   NewFromFloat(0).StringFixedBank(0) // output: "0"
+// 	   NewFromFloat(5.45).StringFixedBank(0) // output: "5"
+// 	   NewFromFloat(5.45).StringFixedBank(1) // output: "5.4"
+// 	   NewFromFloat(5.45).StringFixedBank(2) // output: "5.45"
+// 	   NewFromFloat(5.45).StringFixedBank(3) // output: "5.450"
+// 	   NewFromFloat(545).StringFixedBank(-1) // output: "540"
 //
 func (d Decimal) StringFixedBank(places int32) string {
 	rounded := d.RoundBank(places)
@@ -1167,7 +1169,7 @@ func Avg(first Decimal, rest ...Decimal) Decimal {
 	return sum.Div(count)
 }
 
-// Rescale two decimals to common exponential value (minimal exp of both decimals)
+// RescalePair rescales two decimals to common exponential value (minimal exp of both decimals)
 func RescalePair(d1 Decimal, d2 Decimal) (Decimal, Decimal) {
 	d1.ensureInitialized()
 	d2.ensureInitialized()

rounding.go

@@ -8,6 +8,7 @@
 // Can do binary floating point in multiprecision decimal precisely
 // because 2 divides 10; cannot do decimal floating point
 // in multiprecision binary precisely.
+
 package decimal
 
 type floatInfo struct {