Update API documentation for 2.0 release

This patch updates the existing API documentation and adds new documentation for types and methods that lack it.

Patch by João Reis; reviewed by Bohdan Siryk for CASSGO-78

Author: joao-r-reis

CHANGELOG.md

@@ -35,6 +35,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add way to create HostInfo objects for testing purposes (CASSGO-71)
 - Add missing Context methods on Query and Batch (CASSGO-81)
 - Update example and test code for 2.0 release (CASSGO-80)
+- Add API docs for 2.0 release (CASSGO-78)
 
 ### Changed
 

address_translators.go

@@ -36,6 +36,7 @@ type AddressTranslator interface {
 	Translate(addr net.IP, port int) (net.IP, int)
 }
 
+// AddressTranslatorFunc is a function type that implements AddressTranslator.
 type AddressTranslatorFunc func(addr net.IP, port int) (net.IP, int)
 
 func (fn AddressTranslatorFunc) Translate(addr net.IP, port int) (net.IP, int) {

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")
 )

compressor.go

@@ -24,6 +24,9 @@
 
 package gocql
 
+// Compressor defines the interface for frame compression and decompression.
+// Implementations provide compression algorithms like Snappy and LZ4 that can be used
+// to reduce network traffic between the driver and Cassandra nodes.
 type Compressor interface {
 	Name() string
 

conn.go

@@ -68,6 +68,7 @@ func JoinHostPort(addr string, port int) string {
 	return addr
 }
 
+// Authenticator handles authentication challenges and responses during connection setup.
 type Authenticator interface {
 	Challenge(req []byte) (resp []byte, auth Authenticator, err error)
 	Success(data []byte) error
@@ -132,6 +133,7 @@ type SslOptions struct {
 	EnableHostVerification bool
 }
 
+// ConnConfig contains configuration options for establishing connections to Cassandra nodes.
 type ConnConfig struct {
 	ProtoVersion   int
 	CQLVersion     string
@@ -150,6 +152,7 @@ type ConnConfig struct {
 	disableCoalesce bool
 }
 
+// ConnErrorHandler handles connection errors and state changes for connections.
 type ConnErrorHandler interface {
 	HandleError(conn *Conn, err error, closed bool)
 }

cqltypes.go

@@ -24,6 +24,7 @@
 
 package gocql
 
+// Duration represents a Cassandra duration type, which consists of months, days, and nanoseconds components.
 type Duration struct {
 	Months      int32
 	Days        int32

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