Add and improve a bunch of docstrings

Author: mhagger

counts/counts.go

@@ -4,21 +4,25 @@ import (
 	"math"
 )
 
-// A count of something, capped at math.MaxUint32.
+// Count32 is a count of something, capped at math.MaxUint32.
 type Count32 uint32
 
+// NewCount32 initializes a Count32 from a uint64, capped at
+// math.MaxUint32.
 func NewCount32(n uint64) Count32 {
 	if n > math.MaxUint32 {
 		return Count32(math.MaxUint32)
 	}
 	return Count32(n)
 }
 
+// ToUint64 returns the value of `n` as a `uint64`. If the value has
+// overflowed, it returns `(math.MaxUint32, true)`.
 func (n Count32) ToUint64() (uint64, bool) {
 	return uint64(n), n == math.MaxUint32
 }
 
-// Return the sum of two Count32s, capped at math.MaxUint32.
+// Plus returns the sum of two Count32s, capped at math.MaxUint32.
 func (n1 Count32) Plus(n2 Count32) Count32 {
 	n := n1 + n2
 	if n < n1 {
@@ -28,7 +32,7 @@ func (n1 Count32) Plus(n2 Count32) Count32 {
 	return n
 }
 
-// Increment `*n1` by `n2`, capped at math.MaxUint32.
+// Increment increases `*n1` by `n2`, capped at math.MaxUint32.
 func (n1 *Count32) Increment(n2 Count32) {
 	*n1 = n1.Plus(n2)
 }
@@ -55,18 +59,21 @@ func (n1 *Count32) AdjustMaxIfPossible(n2 Count32) bool {
 	}
 }
 
-// A count of something, capped at math.MaxUint64.
+// Count64 is a count of something, capped at math.MaxUint64.
 type Count64 uint64
 
+// NewCount64 initializes a Count64 from a uint64.
 func NewCount64(n uint64) Count64 {
 	return Count64(n)
 }
 
+// ToUint64 returns the value of `n` as a `uint64`. If the value has
+// overflowed, it returns `(math.MaxUint64, true)`.
 func (n Count64) ToUint64() (uint64, bool) {
 	return uint64(n), n == math.MaxUint64
 }
 
-// Return the sum of two Count64s, capped at math.MaxUint64.
+// Plus returns the sum of two Count64s, capped at math.MaxUint64.
 func (n1 Count64) Plus(n2 Count64) Count64 {
 	n := n1 + n2
 	if n < n1 {
@@ -76,7 +83,7 @@ func (n1 Count64) Plus(n2 Count64) Count64 {
 	return n
 }
 
-// Increment `*n1` by `n2`, capped at math.MaxUint64.
+// Increment increases `*n1` by `n2`, capped at math.MaxUint64.
 func (n1 *Count64) Increment(n2 Count64) {
 	*n1 = n1.Plus(n2)
 }

counts/human.go

@@ -4,24 +4,28 @@ import (
 	"fmt"
 )
 
-// A quantity that can be made human-readable using Human().
+// Humanable is a quantity that can be made human-readable using
+// `Humaner.Format()`.
 type Humanable interface {
-	// Return the value as a uint64, and a boolean telling whether it
-	// overflowed.
+	// ToUint64 returns the value as a uint64, and a boolean telling
+	// whether it overflowed.
 	ToUint64() (uint64, bool)
 }
 
-// An object that can format a Humanable in human-readable format.
+// Humaner is an object that can format a Humanable in human-readable
+// format.
 type Humaner struct {
 	name     string
 	prefixes []Prefix
 }
 
+// Prefix is a metric-like prefix that implies a scaling factor.
 type Prefix struct {
 	Name       string
 	Multiplier uint64
 }
 
+// Metric is a Humaner representing metric prefixes.
 var Metric = Humaner{
 	name: "metric",
 	prefixes: []Prefix{
@@ -34,6 +38,8 @@ var Metric = Humaner{
 	},
 }
 
+// Binary is a Humaner representing power-of-1024 based prefixes,
+// typically used for bytes.
 var Binary = Humaner{
 	name: "binary",
 	prefixes: []Prefix{
@@ -46,12 +52,14 @@ var Binary = Humaner{
 	},
 }
 
+// Name returns the name of `h` ("metric" or "binary").
 func (h *Humaner) Name() string {
 	return h.name
 }
 
-// Format n, aligned, in `len(unit) + 10` or fewer characters (except
-// for extremely large numbers).
+// FormatNumber formats n, aligned, in `len(unit) + 10` or fewer
+// characters (except for extremely large numbers). It returns strings
+// representing the numeral and the unit string.
 func (h *Humaner) FormatNumber(n uint64, unit string) (string, string) {
 	prefix := h.prefixes[0]
 
@@ -82,8 +90,9 @@ func (h *Humaner) FormatNumber(n uint64, unit string) (string, string) {
 	}
 }
 
-// Format values, aligned, in `len(unit) + 10` or fewer characters
-// (except for extremely large numbers).
+// Format formats values, aligned, in `len(unit) + 10` or fewer
+// characters (except for extremely large numbers). It returns strings
+// representing the numeral and the unit string.
 func (h *Humaner) Format(value Humanable, unit string) (string, string) {
 	n, overflow := value.ToUint64()
 	if overflow {