user API doc enhancement

Author: tengu-alt

address_translators.go

@@ -36,8 +36,10 @@ type AddressTranslator interface {
 	Translate(addr net.IP, port int) (net.IP, int)
 }
 
+// AddressTranslatorFunc implements AddressTranslator interface.
 type AddressTranslatorFunc func(addr net.IP, port int) (net.IP, int)
 
+// Translate translates address and port.
 func (fn AddressTranslatorFunc) Translate(addr net.IP, port int) (net.IP, int) {
 	return fn(addr, port)
 }

conn.go

@@ -84,6 +84,8 @@ type PasswordAuthenticator struct {
 	AllowedAuthenticators []string
 }
 
+// Challenge creates challenge response for auth handshake.
+// Returns an error if authenticator is not approved.
 func (p PasswordAuthenticator) Challenge(req []byte) ([]byte, Authenticator, error) {
 	if !approve(string(req), p.AllowedAuthenticators) {
 		return nil, nil, fmt.Errorf("unexpected authenticator %q", req)
@@ -96,6 +98,7 @@ func (p PasswordAuthenticator) Challenge(req []byte) ([]byte, Authenticator, err
 	return resp, nil, nil
 }
 
+// Success used in case of success auth handshake.
 func (p PasswordAuthenticator) Success(data []byte) error {
 	return nil
 }
@@ -131,6 +134,7 @@ type SslOptions struct {
 	EnableHostVerification bool
 }
 
+// ConnConfig configures connection used by the driver.
 type ConnConfig struct {
 	ProtoVersion   int
 	CQLVersion     string
@@ -321,10 +325,15 @@ func (c *Conn) init(ctx context.Context, dialedHost *DialedHost) error {
 	return nil
 }
 
+// Write writes p to the connection.
+// It returns the number of bytes written from p (0 <= n <= len(p)) and any error that caused the write to stop
+// early.
 func (c *Conn) Write(p []byte) (n int, err error) {
 	return c.w.writeContext(context.Background(), p)
 }
 
+// Read reads exactly len(p) bytes from Conn reader into p.
+// It returns the number of bytes copied and an error if fewer bytes were read.
 func (c *Conn) Read(p []byte) (n int, err error) {
 	const maxAttempts = 5
 
@@ -561,6 +570,7 @@ func (c *Conn) close() error {
 	return c.conn.Close()
 }
 
+// Close closes the connection.
 func (c *Conn) Close() {
 	c.closeWithError(nil)
 }
@@ -1475,27 +1485,32 @@ func (c *Conn) executeQuery(ctx context.Context, qry *Query) *Iter {
 	}
 }
 
+// Pick returns nil if connection is closed.
 func (c *Conn) Pick(qry *Query) *Conn {
 	if c.Closed() {
 		return nil
 	}
 	return c
 }
 
+// Closed returns true if connection close process for the connection started.
 func (c *Conn) Closed() bool {
 	c.mu.Lock()
 	defer c.mu.Unlock()
 	return c.closed
 }
 
+// Address returns address used for the connection.
 func (c *Conn) Address() string {
 	return c.addr
 }
 
+// AvailableStreams returns the number of the available streams.
 func (c *Conn) AvailableStreams() int {
 	return c.streams.Available()
 }
 
+// UseKeyspace executes `USE <keyspace>;` query and set keyspace as current.
 func (c *Conn) UseKeyspace(keyspace string) error {
 	q := &writeQueryFrame{statement: `USE "` + keyspace + `"`}
 	q.params.consistency = c.session.cons

filters.go

@@ -47,6 +47,7 @@ func AcceptAllFilter() HostFilter {
 	})
 }
 
+// DenyAllFilter will deny all hosts
 func DenyAllFilter() HostFilter {
 	return HostFilterFunc(func(host *HostInfo) bool {
 		return false
@@ -61,12 +62,6 @@ func DataCenterHostFilter(dataCenter string) HostFilter {
 	})
 }
 
-// Deprecated: Use DataCenterHostFilter instead.
-// DataCentreHostFilter is an alias that doesn't use the preferred spelling.
-func DataCentreHostFilter(dataCenter string) HostFilter {
-	return DataCenterHostFilter(dataCenter)
-}
-
 // WhiteListHostFilter filters incoming hosts by checking that their address is
 // in the initial hosts whitelist.
 func WhiteListHostFilter(hosts ...string) HostFilter {

frame.go

@@ -260,6 +260,7 @@ func (c *Consistency) UnmarshalText(text []byte) error {
 	return nil
 }
 
+// ParseConsistency returns parsed consistency or panics in case of an error.
 func ParseConsistency(s string) Consistency {
 	var c Consistency
 	if err := c.UnmarshalText([]byte(strings.ToUpper(s))); err != nil {
@@ -343,6 +344,7 @@ func (f frameHeader) Header() frameHeader {
 
 const defaultBufSize = 128
 
+// ObservedFrameHeader observe header of the frame.
 type ObservedFrameHeader struct {
 	Version protoVersion
 	Flags   byte

helpers.go

@@ -35,6 +35,7 @@ import (
 	"gopkg.in/inf.v0"
 )
 
+// RowData contains values and column names of a single row.
 type RowData struct {
 	Columns []string
 	Values  []interface{}

host_source.go

@@ -155,6 +155,7 @@ func (c cassVersion) nodeUpDelay() time.Duration {
 	return 10 * time.Second
 }
 
+// HostInfo holds information about the host (e.g. addresses and state).
 type HostInfo struct {
 	// TODO(zariel): reduce locking maybe, not all values will change, but to ensure
 	// that we are thread safe use a mutex to access all fields.
@@ -181,6 +182,7 @@ type HostInfo struct {
 	tokens           []string
 }
 
+// Equal returns true if hosts are equal of if connect addresses of the hosts are equal.
 func (h *HostInfo) Equal(host *HostInfo) bool {
 	if h == host {
 		// prevent rlock reentry
@@ -190,6 +192,7 @@ func (h *HostInfo) Equal(host *HostInfo) bool {
 	return h.ConnectAddress().Equal(host.ConnectAddress())
 }
 
+// Peer returns hosts peer.
 func (h *HostInfo) Peer() net.IP {
 	h.mu.RLock()
 	defer h.mu.RUnlock()
@@ -260,92 +263,107 @@ func (h *HostInfo) SetConnectAddress(address net.IP) *HostInfo {
 	return h
 }
 
+// BroadcastAddress returns the broadcast address of the host.
 func (h *HostInfo) BroadcastAddress() net.IP {
 	h.mu.RLock()
 	defer h.mu.RUnlock()
 	return h.broadcastAddress
 }
 
+// ListenAddress returns the address on which a host listens for incoming connections.
 func (h *HostInfo) ListenAddress() net.IP {
 	h.mu.RLock()
 	defer h.mu.RUnlock()
 	return h.listenAddress
 }
 
+// RPCAddress returns address on which host listens for RPC requests.
 func (h *HostInfo) RPCAddress() net.IP {
 	h.mu.RLock()
 	defer h.mu.RUnlock()
 	return h.rpcAddress
 }
 
+// PreferredIP returns the preferred IP of the host.
 func (h *HostInfo) PreferredIP() net.IP {
 	h.mu.RLock()
 	defer h.mu.RUnlock()
 	return h.preferredIP
 }
 
+// DataCenter returns the name of the host data center.
 func (h *HostInfo) DataCenter() string {
 	h.mu.RLock()
 	dc := h.dataCenter
 	h.mu.RUnlock()
 	return dc
 }
 
+// Rack returns the name of the host rack.
 func (h *HostInfo) Rack() string {
 	h.mu.RLock()
 	rack := h.rack
 	h.mu.RUnlock()
 	return rack
 }
 
+// HostID returns the host ID.
 func (h *HostInfo) HostID() string {
 	h.mu.RLock()
 	defer h.mu.RUnlock()
 	return h.hostId
 }
 
+// SetHostID sets the host ID.
 func (h *HostInfo) SetHostID(hostID string) {
 	h.mu.Lock()
 	defer h.mu.Unlock()
 	h.hostId = hostID
 }
 
+// WorkLoad returns the current workload of the host.
 func (h *HostInfo) WorkLoad() string {
 	h.mu.RLock()
 	defer h.mu.RUnlock()
 	return h.workload
 }
 
+// Graph returns true if graph mode is enabled for the DSE.
 func (h *HostInfo) Graph() bool {
 	h.mu.RLock()
 	defer h.mu.RUnlock()
 	return h.graph
 }
 
+// DSEVersion returns the version of DSE instance.
 func (h *HostInfo) DSEVersion() string {
 	h.mu.RLock()
 	defer h.mu.RUnlock()
 	return h.dseVersion
 }
 
+// Partitioner returns the partitioner kind.
 func (h *HostInfo) Partitioner() string {
 	h.mu.RLock()
 	defer h.mu.RUnlock()
 	return h.partitioner
 }
 
+// ClusterName returns name of the cluster.
 func (h *HostInfo) ClusterName() string {
 	h.mu.RLock()
 	defer h.mu.RUnlock()
 	return h.clusterName
 }
 
+// Version returns version of the Cassandra instance.
 func (h *HostInfo) Version() cassVersion {
 	h.mu.RLock()
 	defer h.mu.RUnlock()
 	return h.version
 }
 
+// State returns state of the node.
 func (h *HostInfo) State() nodeState {
 	h.mu.RLock()
 	defer h.mu.RUnlock()
@@ -359,12 +377,14 @@ func (h *HostInfo) setState(state nodeState) *HostInfo {
 	return h
 }
 
+// Tokens returns slice of tokens.
 func (h *HostInfo) Tokens() []string {
 	h.mu.RLock()
 	defer h.mu.RUnlock()
 	return h.tokens
 }
 
+// Port returns port which used for the connection.
 func (h *HostInfo) Port() int {
 	h.mu.RLock()
 	defer h.mu.RUnlock()
@@ -433,10 +453,13 @@ func (h *HostInfo) update(from *HostInfo) {
 	}
 }
 
+// IsUp return true if the host is not nil and if the host state is node NodeUp.
 func (h *HostInfo) IsUp() bool {
 	return h != nil && h.State() == NodeUp
 }
 
+// HostnameAndPort returns a network address of the form "host:port".
+// If host contains a colon - "[host]:port" will be returned.
 func (h *HostInfo) HostnameAndPort() string {
 	h.mu.Lock()
 	defer h.mu.Unlock()
@@ -447,6 +470,8 @@ func (h *HostInfo) HostnameAndPort() string {
 	return net.JoinHostPort(h.hostname, strconv.Itoa(h.port))
 }
 
+// ConnectAddressAndPort returns a network address of the form "host:port".
+// If connect address contains a colon - "[host]:port" will be returned.
 func (h *HostInfo) ConnectAddressAndPort() string {
 	h.mu.Lock()
 	defer h.mu.Unlock()

marshal.go

@@ -2469,6 +2469,7 @@ type TypeInfo interface {
 	NewWithError() (interface{}, error)
 }
 
+// NativeType describes a Cassandra native types
 type NativeType struct {
 	proto  byte
 	typ    Type
@@ -2487,14 +2488,17 @@ func (t NativeType) NewWithError() (interface{}, error) {
 	return reflect.New(typ).Interface(), nil
 }
 
+// Type returns identifier of a Cassandra internal datatype.
 func (s NativeType) Type() Type {
 	return s.typ
 }
 
+// Version returns native protocol version of a type.
 func (s NativeType) Version() byte {
 	return s.proto
 }
 
+// Custom returns the name of custom class.
 func (s NativeType) Custom() string {
 	return s.custom
 }
@@ -2508,6 +2512,7 @@ func (s NativeType) String() string {
 	}
 }
 
+// CollectionType describes a Cassandra collection types.
 type CollectionType struct {
 	NativeType
 	Key  TypeInfo // only used for TypeMap
@@ -2535,6 +2540,7 @@ func (c CollectionType) String() string {
 	}
 }
 
+// TupleTypeInfo describes a Cassandra tuple types.
 type TupleTypeInfo struct {
 	NativeType
 	Elems []TypeInfo
@@ -2564,6 +2570,7 @@ type UDTField struct {
 	Type TypeInfo
 }
 
+// UDTTypeInfo describes a Cassandra UDT types.
 type UDTTypeInfo struct {
 	NativeType
 	KeySpace string

metadata.go

@@ -136,6 +136,7 @@ type MaterializedViewMetadata struct {
 	baseTableName string
 }
 
+// UserTypeMetadata holds the metadata for user types.
 type UserTypeMetadata struct {
 	Keyspace   string
 	Name       string