add API docs for public api elements that don't have them

Author: joao-r-reis

cluster.go

@@ -288,6 +288,11 @@ type ClusterConfig struct {
 	disableControlConn bool
 }
 
+// Dialer is the interface that wraps the DialContext method for establishing network connections to Cassandra nodes.
+//
+// This interface allows customization of how gocql establishes TCP connections, which is useful for:
+// connecting through proxies or load balancers, custom TLS configurations, custom timeouts/keep-alive
+// settings, service mesh integration, testing with mocked connections, and corporate network routing.
 type Dialer interface {
 	DialContext(ctx context.Context, network, addr string) (net.Conn, error)
 }
@@ -357,7 +362,10 @@ func (cfg *ClusterConfig) filterHost(host *HostInfo) bool {
 }
 
 var (
-	ErrNoHosts              = errors.New("no hosts provided")
+	// ErrNoHosts is returned when no hosts are provided to the cluster configuration.
+	ErrNoHosts = errors.New("no hosts provided")
+	// ErrNoConnectionsStarted is returned when no connections could be established during session creation.
 	ErrNoConnectionsStarted = errors.New("no connections were made when creating the session")
-	ErrHostQueryFailed      = errors.New("unable to populate Hosts")
+	// Deprecated: Never used or returned by the driver.
+	ErrHostQueryFailed = errors.New("unable to populate Hosts")
 )

errors.go

@@ -111,6 +111,7 @@ const (
 	ErrCodeUnprepared = 0x2500
 )
 
+// RequestError represents errors returned by Cassandra server.
 type RequestError interface {
 	Code() int
 	Message() string
@@ -140,6 +141,8 @@ func (e errorFrame) String() string {
 	return fmt.Sprintf("[error code=%x message=%q]", e.code, e.message)
 }
 
+// RequestErrUnavailable represents an unavailable error returned by Cassandra.
+// This error occurs when there are not enough nodes available to fulfill the request.
 type RequestErrUnavailable struct {
 	errorFrame
 	Consistency Consistency
@@ -151,8 +154,14 @@ func (e *RequestErrUnavailable) String() string {
 	return fmt.Sprintf("[request_error_unavailable consistency=%s required=%d alive=%d]", e.Consistency, e.Required, e.Alive)
 }
 
+// ErrorMap maps node IP addresses to their respective error codes for read/write failure responses.
+// Each entry represents a node that failed during the operation, with the key being the node's
+// IP address as a string and the value being the specific error code returned by that node.
 type ErrorMap map[string]uint16
 
+// RequestErrWriteTimeout represents a write timeout error returned by Cassandra.
+// This error occurs when a write request times out after the coordinator
+// has successfully written to some replicas but not enough to satisfy the required consistency level.
 type RequestErrWriteTimeout struct {
 	errorFrame
 	Consistency Consistency
@@ -161,6 +170,8 @@ type RequestErrWriteTimeout struct {
 	WriteType   string
 }
 
+// RequestErrWriteFailure represents a write failure error returned by Cassandra.
+// This error occurs when a write request fails on one or more replicas.
 type RequestErrWriteFailure struct {
 	errorFrame
 	Consistency Consistency
@@ -171,10 +182,15 @@ type RequestErrWriteFailure struct {
 	ErrorMap    ErrorMap
 }
 
+// RequestErrCDCWriteFailure represents a CDC write failure error returned by Cassandra.
+// This error occurs when a write to the Change Data Capture log fails.
 type RequestErrCDCWriteFailure struct {
 	errorFrame
 }
 
+// RequestErrReadTimeout represents a read timeout error returned by Cassandra.
+// This error occurs when a read request times out after the coordinator
+// has received some responses but not enough to satisfy the required consistency level.
 type RequestErrReadTimeout struct {
 	errorFrame
 	Consistency Consistency
@@ -183,17 +199,23 @@ type RequestErrReadTimeout struct {
 	DataPresent byte
 }
 
+// RequestErrAlreadyExists represents an "already exists" error returned by Cassandra.
+// This error occurs when attempting to create a keyspace or table that already exists.
 type RequestErrAlreadyExists struct {
 	errorFrame
 	Keyspace string
 	Table    string
 }
 
+// RequestErrUnprepared represents an "unprepared" error returned by Cassandra.
+// This error occurs when a prepared statement is no longer available on the server.
 type RequestErrUnprepared struct {
 	errorFrame
 	StatementId []byte
 }
 
+// RequestErrReadFailure represents a read failure error returned by Cassandra.
+// This error occurs when a read request fails on one or more replicas.
 type RequestErrReadFailure struct {
 	errorFrame
 	Consistency Consistency
@@ -204,6 +226,8 @@ type RequestErrReadFailure struct {
 	ErrorMap    ErrorMap
 }
 
+// RequestErrFunctionFailure represents a function failure error returned by Cassandra.
+// This error occurs when a user-defined function fails during execution.
 type RequestErrFunctionFailure struct {
 	errorFrame
 	Keyspace string

frame.go

@@ -196,6 +196,9 @@ const (
 	flagBetaProtocol  byte = 0x10
 )
 
+// Consistency represents the consistency level for read and write operations.
+// Available levels: Any, One, Two, Three, Quorum, All, LocalQuorum, EachQuorum, 
+// Serial, LocalSerial, LocalOne.
 type Consistency uint16
 
 // SerialConsistency is deprecated. Use Consistency instead.

gocqlzap/zap.go

@@ -24,8 +24,11 @@ import (
 	gocql "github.com/apache/cassandra-gocql-driver/v2"
 )
 
+// DefaultName is the default logger name used when creating a new zap logger.
 const DefaultName = "gocql"
 
+// Logger represents a structured logger that integrates zap logging with gocql.
+// It extends gocql.StructuredLogger with access to the underlying zap logger.
 type Logger interface {
 	gocql.StructuredLogger
 	ZapLogger() *zap.Logger

gocqlzerolog/zerolog.go

@@ -24,9 +24,14 @@ import (
 	gocql "github.com/apache/cassandra-gocql-driver/v2"
 )
 
+// DefaultName is the default logger name used when creating a new zerolog logger.
 const DefaultName = "gocql"
+
+// DefaultNameField is the default field name used to identify the logger in log entries.
 const DefaultNameField = "logger"
 
+// Logger represents a structured logger that integrates zerolog logging with gocql.
+// It extends gocql.StructuredLogger with access to the underlying zerolog logger.
 type Logger interface {
 	gocql.StructuredLogger
 	ZerologLogger() zerolog.Logger

logger.go

@@ -183,6 +183,9 @@ func writeLogMsg(buf *bytes.Buffer, prefix string, msg string, fields []LogField
 	writeFields(buf, fields)
 }
 
+// LogLevel represents the level of logging to be performed.
+// Higher values indicate more verbose logging.
+// Available levels: LogLevelDebug, LogLevelInfo, LogLevelWarn, LogLevelError, LogLevelNone.
 type LogLevel int
 
 const (
@@ -212,6 +215,8 @@ func (recv LogLevel) String() string {
 	}
 }
 
+// LogField represents a structured log field with a name and value.
+// It is used to provide structured logging information.
 type LogField struct {
 	Name  string
 	Value LogFieldValue
@@ -277,7 +282,9 @@ type LogFieldValue struct {
 	any interface{}
 }
 
-// LogFieldValueType is the type of a LogFieldValue.
+// LogFieldValueType represents the type of a LogFieldValue.
+// It is used to determine how to interpret the value stored in LogFieldValue.
+// Available types: LogFieldTypeAny, LogFieldTypeBool, LogFieldTypeInt64, LogFieldTypeString.
 type LogFieldValueType int
 
 // It's important that LogFieldTypeAny is 0 so that a zero Value represents nil.

marshal.go

@@ -47,6 +47,7 @@ var (
 )
 
 var (
+	// Deprecated: Never used or returned by the driver.
 	ErrorUDTUnavailable = errors.New("UDT are not available on protocols less than 3, please update config")
 )
 
@@ -1807,6 +1808,8 @@ func (t listSetCQLType) TypeInfoFromString(proto int, name string) (TypeInfo, er
 	}, nil
 }
 
+// CollectionType represents type information for Cassandra collection types (list, set, map).
+// It provides marshaling and unmarshaling for collection types.
 type CollectionType struct {
 	typ  Type
 	Key  TypeInfo // only used for TypeMap
@@ -2483,7 +2486,8 @@ func (t tupleCQLType) TypeInfoFromString(proto int, name string) (TypeInfo, erro
 	}, nil
 }
 
-// TODO: move to types.go
+// TupleTypeInfo represents type information for Cassandra tuple types.
+// It contains information about the element types in the tuple.
 type TupleTypeInfo struct {
 	Elems []TypeInfo
 }
@@ -2823,11 +2827,15 @@ func (u udtCQLType) TypeInfoFromString(proto int, name string) (TypeInfo, error)
 	return ti, nil
 }
 
+// UDTField represents a field in a User Defined Type.
+// It contains the field name and its type information.
 type UDTField struct {
 	Name string
 	Type TypeInfo
 }
 
+// UDTTypeInfo represents type information for Cassandra User Defined Types (UDT).
+// It contains the keyspace, type name, and field definitions.
 type UDTTypeInfo struct {
 	Keyspace string
 	Name     string
@@ -3043,6 +3051,7 @@ func (udt UDTTypeInfo) Unmarshal(data []byte, value interface{}) error {
 	return nil
 }
 
+// MarshalError represents an error that occurred during marshaling.
 type MarshalError string
 
 func (m MarshalError) Error() string {
@@ -3053,6 +3062,7 @@ func marshalErrorf(format string, args ...interface{}) MarshalError {
 	return MarshalError(fmt.Sprintf(format, args...))
 }
 
+// UnmarshalError represents an error that occurred during unmarshaling.
 type UnmarshalError string
 
 func (m UnmarshalError) Error() string {

metadata.go

@@ -135,27 +135,46 @@ type MaterializedViewMetadata struct {
 	baseTableName string
 }
 
+// UserTypeMetadata represents metadata information about a Cassandra User Defined Type (UDT).
+// This Go struct holds descriptive information about a UDT that exists in the Cassandra schema,
+// including the type name, keyspace, field names, and field types. It is not the UDT itself,
+// but rather a representation of the UDT's schema structure for use within the gocql driver.
+//
+// A Cassandra User Defined Type is a custom data type that allows you to group related fields 
+// together. This metadata struct provides the necessary information to marshal and unmarshal
+// values to and from the corresponding UDT in Cassandra.
+//
+// For type information used in marshaling/unmarshaling operations, see UDTTypeInfo.
+// Actual UDT values are typically represented as map[string]interface{}, Go structs with 
+// cql tags, or types implementing UDTMarshaler/UDTUnmarshaler interfaces.
 type UserTypeMetadata struct {
-	Keyspace   string
-	Name       string
-	FieldNames []string
-	FieldTypes []TypeInfo
+	Keyspace   string     // The keyspace where the UDT is defined
+	Name       string     // The name of the User Defined Type
+	FieldNames []string   // Ordered list of field names in the UDT
+	FieldTypes []TypeInfo // Corresponding type information for each field
 }
 
-// the ordering of the column with regard to its comparator
+// ColumnOrder represents the ordering of a column with regard to its comparator.
+// It indicates whether the column is sorted in ascending or descending order.
+// Available values: ASC, DESC.
 type ColumnOrder bool
 
 const (
 	ASC  ColumnOrder = false
 	DESC ColumnOrder = true
 )
 
+// ColumnIndexMetadata represents metadata for a column index in Cassandra.
+// It contains the index name, type, and configuration options.
 type ColumnIndexMetadata struct {
 	Name    string
 	Type    string
 	Options map[string]interface{}
 }
 
+// ColumnKind represents the kind of column in a Cassandra table.
+// It indicates whether the column is part of the partition key, clustering key, or a regular column.
+// Available values: ColumnUnkownKind, ColumnPartitionKey, ColumnClusteringKey, ColumnRegular, ColumnCompact, ColumnStatic.
 type ColumnKind int
 
 const (

policies.go

@@ -122,6 +122,8 @@ type RetryableQuery interface {
 	Context() context.Context
 }
 
+// RetryType represents the type of retry that should be performed by the retry policy.
+// Available types: Retry, RetryNextHost, Ignore, Rethrow.
 type RetryType uint16
 
 const (
@@ -265,13 +267,18 @@ func (e *ExponentialBackoffRetryPolicy) napTime(attempts int) time.Duration {
 	return getExponentialTime(e.Min, e.Max, attempts)
 }
 
+// HostStateNotifier is an interface for notifying about host state changes.
+// It allows host selection policies to be informed when hosts are added, removed,
+// or change their availability status.
 type HostStateNotifier interface {
 	AddHost(host *HostInfo)
 	RemoveHost(host *HostInfo)
 	HostUp(host *HostInfo)
 	HostDown(host *HostInfo)
 }
 
+// KeyspaceUpdateEvent represents a keyspace change event.
+// It contains information about which keyspace changed and what type of change occurred.
 type KeyspaceUpdateEvent struct {
 	Keyspace string
 	Change   string
@@ -947,16 +954,22 @@ func (e *ExponentialReconnectionPolicy) GetMaxRetries() int {
 	return e.MaxRetries
 }
 
+// SpeculativeExecutionPolicy defines the interface for speculative execution policies.
+// These policies determine when and how many speculative queries to execute.
 type SpeculativeExecutionPolicy interface {
 	Attempts() int
 	Delay() time.Duration
 }
 
+// NonSpeculativeExecution is a policy that disables speculative execution.
+// It implements SpeculativeExecutionPolicy with zero attempts.
 type NonSpeculativeExecution struct{}
 
 func (sp NonSpeculativeExecution) Attempts() int        { return 0 } // No additional attempts
 func (sp NonSpeculativeExecution) Delay() time.Duration { return 1 } // The delay. Must be positive to be used in a ticker.
 
+// SimpleSpeculativeExecution is a policy that enables speculative execution
+// with a fixed number of attempts and delay.
 type SimpleSpeculativeExecution struct {
 	NumAttempts  int
 	TimeoutDelay time.Duration