make sure exported functions are godoc'd

bitmap.go

@@ -174,13 +174,16 @@ func (b *Bitmap) InvalidateCount() {
 	}
 }
 
-//increment the bitmap cached counter, note this is an optimization that assumes that the caller is aware the size increased
+// IncrementCount increments the bitmap cached counter, note this is an optimization that assumes that the caller is aware the size increased.
 func (b *Bitmap) IncrementCount(i uint64) {
 	seg := b.segment(i / SliceWidth)
 	if seg != nil {
 		seg.n++
 	}
+
 }
+
+// DecrementCount decrements the bitmap cached counter.
 func (b *Bitmap) DecrementCount(i uint64) {
 	seg := b.segment(i / SliceWidth)
 	if seg != nil {

cache.go

@@ -257,6 +257,7 @@ func (p BitmapPairs) Swap(i, j int)      { p[i], p[j] = p[j], p[i] }
 func (p BitmapPairs) Len() int           { return len(p) }
 func (p BitmapPairs) Less(i, j int) bool { return p[i].Count > p[j].Count }
 
+// Pair holds a bitmap id and its count.
 type Pair struct {
 	ID    uint64 `json:"id"`
 	Count uint64 `json:"count"`
@@ -276,12 +277,14 @@ func decodePair(pb *internal.Pair) Pair {
 	}
 }
 
+// Pairs is a sortable slice of Pair objects.
 type Pairs []Pair
 
 func (p Pairs) Swap(i, j int)      { p[i], p[j] = p[j], p[i] }
 func (p Pairs) Len() int           { return len(p) }
 func (p Pairs) Less(i, j int) bool { return p[i].Count > p[j].Count }
 
+// PairHeap is a heap implementation over a group of Pairs.
 type PairHeap struct {
 	Pairs
 }
@@ -412,11 +415,13 @@ type SimpleCache struct {
 	cache map[uint64]*Bitmap
 }
 
+// Fetch retrieves the bitmap at the id in the cache.
 func (s *SimpleCache) Fetch(id uint64) (*Bitmap, bool) {
 	m, ok := s.cache[id]
 	return m, ok
 }
 
+// Add adds the bitmap to the cache, keyed on the id.
 func (s *SimpleCache) Add(id uint64, b *Bitmap) {
 	s.cache[id] = b
 }

cmd.go

@@ -2,12 +2,15 @@ package pilosa
 
 import "io"
 
+// CmdIO holds standard unix inputs and outputs.
 type CmdIO struct {
 	Stdin  io.Reader
 	Stdout io.Writer
 	Stderr io.Writer
 }
 
+// NewCmdIO returns a new instance of CmdIO with inputs and outputs set to the
+// arguments.
 func NewCmdIO(stdin io.Reader, stdout, stderr io.Writer) *CmdIO {
 	return &CmdIO{
 		Stdin:  stdin,

cmd/doc.go

@@ -1,4 +1,15 @@
 /*
 Package cmd contains all the pilosa subcommand definitions (1 per file).
+
+Each command file has an init function and a New*Cmd function, as well as a
+global exported instance of the command.
+
+The New*Cmd function is a function which returns a cobra.Command object wrapping this subcommand.
+
+The init function adds the New*Cmd to a map of subcommand functions which
+ensures that no two commands have the same name, and is used when a new root
+command is created to instantiate all of the subcommands.
+
+The instance of the command is global and exported so that it can be tested.
 */
 package cmd

cmd/server.go

@@ -13,7 +13,7 @@ import (
 	"github.com/pilosa/pilosa/server"
 )
 
-// Serve is global so that tests can control and verify it.
+// Server is global so that tests can control and verify it.
 var Server *server.Command
 
 func NewServeCmd(stdin io.Reader, stdout, stderr io.Writer) *cobra.Command {

config.go

@@ -42,6 +42,8 @@ func NewConfig() *Config {
 	return c
 }
 
+// NewConfigForHosts returns a Config object with Config.Cluster.Nodes already
+// set up.
 func NewConfigForHosts(hosts []string) *Config {
 	conf := NewConfig()
 	for _, hostport := range hosts {

frame.go

@@ -352,6 +352,7 @@ func (f *Frame) Views() []*View {
 	return other
 }
 
+// CreateViewIfNotExists returns the named view, creating it if necessary.
 func (f *Frame) CreateViewIfNotExists(name string) (*View, error) {
 	// Don't create inverse views if they are not enabled.
 	if !f.InverseEnabled() && IsInverseView(name) {

pql/ast.go

@@ -30,9 +30,11 @@ type Call struct {
 	Children []*Call
 }
 
-// UintArg is for reading the value at key from call.Args as a uint64. The value
-// is assumed to be an int64 and then cast to a uint64. An error is returned if
-// the value is not found, or not an int64.
+// UintArg is for reading the value at key from call.Args as a uint64. If the
+// key is not in Call.Args, the value of the returned bool will be false, and
+// the error will be nil. The value is assumed to be a uint64 or an int64 and
+// then cast to a uint64. An error is returned if the value is not an int64 or
+// uint64.
 func (c *Call) UintArg(key string) (uint64, bool, error) {
 	val, ok := c.Args[key]
 	if !ok {
@@ -48,6 +50,10 @@ func (c *Call) UintArg(key string) (uint64, bool, error) {
 	}
 }
 
+// UintSliceArg reads the value at key from call.Args as a slice of uint64. If
+// the key is not in Call.Args, the value of the returned bool will be false,
+// and the error will be nil. If the value is a slice of int64 it will convert
+// it to []uint64. Otherwise, if it is not a []uint64 it will return an error.
 func (c *Call) UintSliceArg(key string) ([]uint64, bool, error) {
 	val, ok := c.Args[key]
 	if !ok {