flesh out docs and pass golint

ostat.go

@@ -1,6 +1,6 @@
-// ostat is a go package that implements the efficient, accurate, and stable
+// Package ostat is a go package that implements the efficient, accurate, and
-// calculation of online statistical quantities. The algorithm comes from *The
+// stable calculation of online statistical quantities. The algorithm comes
-// Art of Computer Programing*, vol 2 by Knuth
+// from *The Art of Computer Programing*, vol 2 by Knuth
 package ostat
 
 import (
@@ -20,6 +20,7 @@ const (
 	Sample
 )
 
+// OnlineStat keeps track of online statistics.
 type OnlineStat struct {
 	n    uint64
 	mean float64
@@ -29,6 +30,10 @@ type OnlineStat struct {
 	typ  uint64
 }
 
+// NewSampleStat returns a ready-to-use OnlineStat for calculating sample
+// statistics.
+//
+// For the distinction between NewSampleStat and NewPopulationStat please refer to https://en.wikipedia.org/wiki/Statistical_population
 func NewSampleStat() *OnlineStat {
 	return &OnlineStat{
 		Min: math.Inf(1),
@@ -37,6 +42,10 @@ func NewSampleStat() *OnlineStat {
 	}
 }
 
+// NewPopulationStat returns a ready-to-use OnlineStat for calculating
+// population statistics.
+//
+// For the distinction between NewSampleStat and NewPopulationStat please refer to https://en.wikipedia.org/wiki/Statistical_population
 func NewPopulationStat() *OnlineStat {
 	return &OnlineStat{
 		Min: math.Inf(1),
@@ -45,6 +54,9 @@ func NewPopulationStat() *OnlineStat {
 	}
 }
 
+// MidStreamStat populates an OnlineStat such that it can pick up where
+// a previous one left off.
+//
 // Let's say you have already stored some values and want to start an
 // OnlineStat mid-stream; This is the function for you! Just provide it with
 // the data in the sinature, and you'll get a properly initialized OnlineStat.
@@ -60,9 +72,9 @@ func MidStreamStat(n uint64, mean, stddev, min, max float64, typ uint64) *Online
 	}
 }
 
-// this is how you feed new values into your OnlineStat.
+// Push is how you feed new values into an OnlineStat.
 func (os *OnlineStat) Push(v float64) {
-	os.n += 1
+	os.n++
 	if v < os.Min {
 		os.Min = v
 	}
@@ -75,7 +87,7 @@ func (os *OnlineStat) Push(v float64) {
 	os.m2 = os.m2 + delta*(v-os.mean)
 }
 
-// http://en.wikipedia.org/wiki/Expected_value
+// Mean as defined by http://en.wikipedia.org/wiki/Expected_value.
 func (os *OnlineStat) Mean() float64 {
 	if os.n == 0 {
 		return 0.0
@@ -83,7 +95,7 @@ func (os *OnlineStat) Mean() float64 {
 	return os.mean
 }
 
-// http://en.wikipedia.org/wiki/Variance
+// Variance as defined by http://en.wikipedia.org/wiki/Variance
 func (os *OnlineStat) Variance() float64 {
 	if os.n == 0 {
 		return 0.0
@@ -91,6 +103,7 @@ func (os *OnlineStat) Variance() float64 {
 	return os.m2 / float64(os.n-os.typ)
 }
 
+// StdDev is the standard deviation as defined by
 // http://en.wikipedia.org/wiki/Variance
 func (os *OnlineStat) StdDev() float64 {
 	return math.Sqrt(os.Variance())
@@ -105,6 +118,7 @@ func (os *OnlineStat) CI() (float64, float64) {
 	return os.mean - dev*conf, os.mean + dev*conf
 }
 
+// N returns how many values have been Pushed into an OnlineStat.
 func (os *OnlineStat) N() uint64 {
 	return os.n
 }
@@ -130,6 +144,7 @@ func (os *OnlineStat) String() string {
 	)
 }
 
+// MarshalJSON is implemented for convenient encoding to json.
 func (os *OnlineStat) MarshalJSON() ([]byte, error) {
 	s := struct {
 		N        uint64  `json:"n"`