better code comments in line with godoc requirements

bin.go

@@ -14,10 +14,10 @@
 
 package aerospike
 
-// BinMap is used to define a map of bin names to values
+// BinMap is used to define a map of bin names to values.
 type BinMap map[string]interface{}
 
-// Column name/value pair.
+// Bin encapsulates a field name/value pair.
 type Bin struct {
 	// Bin name. Current limit is 14 characters.
 	Name string
@@ -26,7 +26,7 @@ type Bin struct {
 	Value Value
 }
 
-// Constructor, specifying bin name and string value.
+// NewBin generates a new Bin instance, specifying bin name and string value.
 // For servers configured as "single-bin", enter an empty name.
 func NewBin(name string, value interface{}) *Bin {
 	return &Bin{
@@ -43,7 +43,7 @@ func binMapToBins(bins BinMap) []*Bin {
 	return binList
 }
 
-// Implements Stringer interface. string representation of bin.
+// String implements Stringer interface.
 func (bn *Bin) String() string {
 	return bn.Name + ":" + bn.Value.String()
 }

client_policy.go

@@ -18,7 +18,7 @@ import (
 	"time"
 )
 
-// Container object for client policy command.
+// ClientPolicy encapsulates parameters for client policy command.
 type ClientPolicy struct {
 	// Initial host connection timeout in milliseconds.  The timeout when opening a connection
 	// to the server host for the first time.
@@ -31,7 +31,7 @@ type ClientPolicy struct {
 	FailIfNotConnected bool //= true
 }
 
-// Generates a new ClientPolicy with default values
+// NewClientPolicy generates a new ClientPolicy with default values.
 func NewClientPolicy() *ClientPolicy {
 	return &ClientPolicy{
 		Timeout:             1 * time.Second,

client_test.go

@@ -346,8 +346,8 @@ var _ = Describe("Aerospike", func() {
 								float64(-math.MaxFloat64): float64(-math.MaxFloat64),
 								float32(math.MaxFloat32):  float32(math.MaxFloat32),
 								float64(math.MaxFloat64):  float64(math.MaxFloat64),
-								true:     true,
-								false:    false,
+								"true":   true,
+								"false":  false,
 								"string": map[interface{}]interface{}{nil: "string", "string": 19}, // map to complex array
 								nil:      []int{18, 41},                                            // array to complex map
 							},
@@ -385,8 +385,8 @@ var _ = Describe("Aerospike", func() {
 
 						bin2 := NewBin("Aerospike2", map[interface{}]interface{}{
 							15:                        nil,
-							true:                      true,
-							false:                     false,
+							"true":                    true,
+							"false":                   false,
 							int8(math.MaxInt8):        int8(math.MaxInt8),
 							int64(math.MinInt64):      int64(math.MinInt64),
 							int64(math.MaxInt64):      int64(math.MaxInt64),

cluster.go

@@ -41,6 +41,8 @@ type atomicNodeArray struct {
 	AtomicArray
 }
 
+// Cluster encapsulates the aerospike cluster nodes and manages
+// them.
 type Cluster struct {
 	// Initial host nodes specified by user.
 	seeds []*Host
@@ -68,6 +70,7 @@ type Cluster struct {
 	closed      AtomicBool
 }
 
+// NewCluster generates a Cluster instance.
 func NewCluster(policy *ClientPolicy, hosts []*Host) (*Cluster, error) {
 	newCluster := &Cluster{
 		seeds:               hosts,
@@ -126,8 +129,8 @@ Loop:
 	clstr.tendChannel <- _TEND_MSG_CLOSED
 }
 
-// Adds new hosts to the cluster
-// They will be added to the cluster on next tend
+// AddSeeds adds new hosts to the cluster.
+// They will be added to the cluster on next tend call.
 func (clstr *Cluster) AddSeeds(hosts []*Host) {
 	clstr.mutex.Lock()
 	defer clstr.mutex.Unlock()
@@ -319,7 +322,7 @@ func (clstr *Cluster) seedNodes() {
 				}
 			}
 
-			if !clstr.FindNodeName(list, nv.name) {
+			if !clstr.findNodeName(list, nv.name) {
 				node := clstr.createNode(nv)
 				clstr.addAliases(node)
 				list = append(list, node)
@@ -332,9 +335,8 @@ func (clstr *Cluster) seedNodes() {
 	}
 }
 
-// FIXIT: This function is not well desined while it is expoted.
 // Finds a node by name in a list of nodes
-func (clstr *Cluster) FindNodeName(list []*Node, name string) bool {
+func (clstr *Cluster) findNodeName(list []*Node, name string) bool {
 	for _, node := range list {
 		if node.GetName() == name {
 			return true
@@ -553,12 +555,14 @@ func (clstr *Cluster) nodeExists(search *Node, nodeList []*Node) bool {
 	return false
 }
 
+// IsConnected returns true if cluster has nodes and is not already closed.
 func (clstr *Cluster) IsConnected() bool {
 	// Must copy array reference for copy on write semantics to work.
 	nodeArray := clstr.GetNodes()
 	return (len(nodeArray) > 0) && !clstr.closed.Get()
 }
 
+// GetNode returns a node for the provided partition.
 func (clstr *Cluster) GetNode(partition *Partition) (*Node, error) {
 	// Must copy hashmap reference for copy on write semantics to work.
 	nmap := clstr.getPartitions()
@@ -572,7 +576,7 @@ func (clstr *Cluster) GetNode(partition *Partition) (*Node, error) {
 	return clstr.GetRandomNode()
 }
 
-// Returns a random node on the cluster
+// GetRandomNode returns a random node on the cluster
 func (clstr *Cluster) GetRandomNode() (*Node, error) {
 	// Must copy array reference for copy on write semantics to work.
 	nodeArray := clstr.GetNodes()
@@ -590,7 +594,7 @@ func (clstr *Cluster) GetRandomNode() (*Node, error) {
 	return nil, NewAerospikeError(INVALID_NODE_ERROR)
 }
 
-// Returns a list of all nodes in the cluster
+// GetNodes returns a list of all nodes in the cluster
 func (clstr *Cluster) GetNodes() []*Node {
 	clstr.mutex.RLock()
 	defer clstr.mutex.RUnlock()
@@ -599,7 +603,8 @@ func (clstr *Cluster) GetNodes() []*Node {
 	return nodeArray
 }
 
-// Find a node by name and returns an error if not found
+// GetNodeByName finds a node by name and returns an
+// error if the node is not found.
 func (clstr *Cluster) GetNodeByName(nodeName string) (*Node, error) {
 	node := clstr.findNodeByName(nodeName)
 
@@ -621,7 +626,8 @@ func (clstr *Cluster) findNodeByName(nodeName string) *Node {
 	return nil
 }
 
-// Closes all cached connections to the cluster nodes and stops the tend goroutine
+// Close closes all cached connections to the cluster nodes
+// and stops the tend goroutine.
 func (clstr *Cluster) Close() {
 	if !clstr.closed.Get() {
 		// send close signal to maintenance channel
@@ -668,6 +674,8 @@ func (clstr *Cluster) MigrationInProgress(timeout time.Duration) (res bool, err
 	}
 }
 
+// WaitUntillMigrationIsFinished will block until all
+// migration operations in the cluster all finished.
 func (clstr *Cluster) WaitUntillMigrationIsFinished(timeout time.Duration) (err error) {
 	done := make(chan error)
 

command.go

@@ -733,7 +733,7 @@ func (cmd *baseCommand) end() {
 // maximum buffer size to keep in the pool: 128K
 var bufPool = NewBufferPool(512, 16*1024, 128*1024)
 
-// SetBufferPool can be used to customize the command Buffer Pool parameters to calibrate
+// SetCommandBufferPool can be used to customize the command Buffer Pool parameters to calibrate
 // the pool for different workloads
 func SetCommandBufferPool(poolSize, initBufSize, maxBufferSize int) {
 	bufPool = NewBufferPool(poolSize, initBufSize, maxBufferSize)

connection.go

@@ -22,7 +22,7 @@ import (
 	. "github.com/aerospike/aerospike-client-go/types"
 )
 
-// Connection represents a connection with a timeout
+// Connection represents a connection with a timeout.
 type Connection struct {
 	// timeout
 	timeout time.Duration
@@ -64,7 +64,7 @@ func NewConnection(address string, timeout time.Duration) (*Connection, error) {
 	return newConn, nil
 }
 
-// Writes the slice to the connection buffer.
+// Write writes the slice to the connection buffer.
 func (ctn *Connection) Write(buf []byte) (total int, err error) {
 	// make sure all bytes are written
 	// Don't worry about the loop, timeout has been set elsewhere
@@ -83,7 +83,7 @@ func (ctn *Connection) Write(buf []byte) (total int, err error) {
 	return total, errToTimeoutErr(err)
 }
 
-// Reads from connection buffer to the slice
+// Read reads from connection buffer to the provided slice.
 func (ctn *Connection) Read(buf []byte, length int) (total int, err error) {
 	// if all bytes are not read, retry until successful
 	// Don't worry about the loop; we've already set the timeout elsewhere
@@ -104,12 +104,12 @@ func (ctn *Connection) Read(buf []byte, length int) (total int, err error) {
 	}
 }
 
-// Returns true if the connection is not closed
+// IsConnected returns true if the connection is not closed yet.
 func (ctn *Connection) IsConnected() bool {
 	return ctn.conn != nil
 }
 
-// sets connection timeout
+// SetTimeout sets connection timeout for both read and write operations.
 func (ctn *Connection) SetTimeout(timeout time.Duration) error {
 	ctn.timeout = timeout
 
@@ -127,7 +127,7 @@ func (ctn *Connection) SetTimeout(timeout time.Duration) error {
 	return nil
 }
 
-// Closes the connection
+// Close closes the connection
 func (ctn *Connection) Close() {
 	if ctn != nil && ctn.conn != nil {
 		if err := ctn.conn.Close(); err != nil {

execute_task.go

@@ -21,15 +21,15 @@ import (
 	. "github.com/aerospike/aerospike-client-go/types"
 )
 
-// Task used to poll for long running server execute job completion.
+// ExecuteTask is used to poll for long running server execute job completion.
 type ExecuteTask struct {
 	BaseTask
 
 	taskId int
 	scan   bool
 }
 
-// Initialize task with fields needed to query server nodes.
+// NewExecuteTask initializes task with fields needed to query server nodes.
 func NewExecuteTask(cluster *Cluster, statement *Statement) *ExecuteTask {
 	return &ExecuteTask{
 		BaseTask: *NewTask(cluster, false),
@@ -38,7 +38,7 @@ func NewExecuteTask(cluster *Cluster, statement *Statement) *ExecuteTask {
 	}
 }
 
-// Query all nodes for task completion status.
+// IsDone queries all nodes for task completion status.
 func (etsk *ExecuteTask) IsDone() (bool, error) {
 	var command string
 	if etsk.scan {
@@ -97,6 +97,10 @@ func (etsk *ExecuteTask) IsDone() (bool, error) {
 	return done, nil
 }
 
+// OnComplete returns a channel which will be closed when the task is
+// completed.
+// If an error is encountered while performing the task, an error
+// will be sent on the channel.
 func (etsk *ExecuteTask) OnComplete() chan error {
 	return etsk.onComplete(etsk)
 }

field_type.go

@@ -21,9 +21,13 @@ const (
 	NAMESPACE FieldType = 0
 	TABLE     FieldType = 1
 	KEY       FieldType = 2
+
 	//BIN FieldType = 3;
+
 	DIGEST_RIPE FieldType = 4
+
 	//GU_TID FieldType = 5;
+
 	DIGEST_RIPE_ARRAY FieldType = 6
 	TRAN_ID           FieldType = 7 // user supplied transaction id, which is simply passed back
 	SCAN_OPTIONS      FieldType = 8

filter.go

@@ -18,21 +18,21 @@ import (
 	Buffer "github.com/aerospike/aerospike-client-go/utils/buffer"
 )
 
-// Query filter definition.
+// Filter specifies a query filter definition.
 type Filter struct {
 	name  string
 	begin Value
 	end   Value
 }
 
-// Create equality filter for query.
+// NewEqualFilter creates a new equality filter instance for query.
 func NewEqualFilter(binName string, value interface{}) *Filter {
 	val := NewValue(value)
 	return newFilter(binName, val, val)
 }
 
-// Create range filter for query.
-// Range arguments must be longs or integers which can be cast to longs.
+// NewRangeFilter creates a range filter for query.
+// Range arguments must be int64 values.
 // String ranges are not supported.
 func NewRangeFilter(binName string, begin int64, end int64) *Filter {
 	return newFilter(binName, NewValue(begin), NewValue(end))

generation_policy.go

@@ -14,21 +14,21 @@
 
 package aerospike
 
-// How to handle record writes based on record generation.
+// GenerationPolicy determines how to handle record writes based on record generation.
 type GenerationPolicy int
 
 const (
-	// Do not use record generation to restrict writes.
+	// NONE means: Do not use record generation to restrict writes.
 	NONE GenerationPolicy = iota
 
-	// Update/delete record if expected generation is equal to server generation. Otherwise, fail.
+	// EXPECT_GEN_EQUAL means: Update/Delete record if expected generation is equal to server generation. Otherwise, fail.
 	EXPECT_GEN_EQUAL
 
-	// Update/delete record if expected generation greater than the server generation. Otherwise, fail.
+	// EXPECT_GEN_GT means: Update/Delete record if expected generation greater than the server generation. Otherwise, fail.
 	// This is useful for restore after backup.
 	EXPECT_GEN_GT
 
-	// Create duplicate record if expected generation is not equal to server generation.
+	// DUPLICATE means: Create duplicate record if expected generation is not equal to server generation.
 	// Duplicates are only created when the server configuration option "allow-versions"
 	// is true (default is false).
 	DUPLICATE

host.go

@@ -30,7 +30,7 @@ type Host struct {
 	addPort string
 }
 
-// Initialize host.
+// NewHost initializes new host instance.
 func NewHost(name string, port int) *Host {
 	return &Host{Name: name, Port: port, addPort: name + ":" + strconv.Itoa(port)}
 }

index_type.go

@@ -14,13 +14,13 @@
 
 package aerospike
 
-// Type of secondary index.
+// IndexType the type of the secondary index.
 type IndexType string
 
 const (
-	// Number index.
+	// NUMERIC specifies an index on numeric values.
 	NUMERIC IndexType = "NUMERIC"
 
-	// String index.
+	// STRING specifies an index on string values.
 	STRING IndexType = "STRING"
 )

info.go

@@ -33,7 +33,7 @@ type info struct {
 	msg *Message
 }
 
-// Get info values by name from the specified database server node.
+// RequestNodeInfo gets info values by name from the specified database server node.
 func RequestNodeInfo(node *Node, name ...string) (map[string]string, error) {
 	conn, err := node.GetConnection(_DEFAULT_TIMEOUT)
 	if err != nil {
@@ -90,7 +90,7 @@ func newInfo(conn *Connection, commands ...string) (*info, error) {
 	return newInfo, nil
 }
 
-// Get info values by name from the specified connection
+// RequestInfo gets info values by name from the specified connection.
 func RequestInfo(conn *Connection, names ...string) (map[string]string, error) {
 	info, err := newInfo(conn, names...)
 	if err != nil {