chore: minor documentation updates, mostly (#73)

- Add some hyperlinks
- Spelling and grammar corrections

auth.go

@@ -22,7 +22,7 @@ const (
 	authClearTextPassword authType = 3
 )
 
-// AuthStrategy represents a authentication strategy used to authenticate a user
+// AuthStrategy represents an authentication strategy used to authenticate a user.
 type AuthStrategy func(ctx context.Context, writer *buffer.Writer, reader *buffer.Reader) (_ context.Context, err error)
 
 // handleAuth handles the client authentication for the given connection.
@@ -44,7 +44,7 @@ func (srv *Server) handleAuth(ctx context.Context, reader *buffer.Reader, writer
 // ClearTextPassword announces to the client to authenticate by sending a
 // clear text password and validates if the provided username and password (received
 // inside the client parameters) are valid. If the provided credentials are invalid
-// or any unexpected error occures is an error returned and should the connection be closed.
+// or any unexpected error occurs, an error returned and the connection should be closed.
 func ClearTextPassword(validate func(ctx context.Context, username, password string) (context.Context, bool, error)) AuthStrategy {
 	return func(ctx context.Context, writer *buffer.Writer, reader *buffer.Reader) (_ context.Context, err error) {
 		err = writeAuthType(writer, authClearTextPassword)
@@ -88,13 +88,13 @@ func writeAuthType(writer *buffer.Writer, status authType) error {
 	return writer.End()
 }
 
-// IsSuperUser checks whether the given connection context is a super user
+// IsSuperUser checks whether the given connection context is a super user.
 func IsSuperUser(ctx context.Context) bool {
 	return false
 }
 
 // AuthenticatedUsername returns the username of the authenticated user of the
-// given connection context
+// given connection context.
 func AuthenticatedUsername(ctx context.Context) string {
 	parameters := ClientParameters(ctx)
 	return parameters[ParamUsername]

cache.go

@@ -121,10 +121,5 @@ func (cache *DefaultPortalCache) Execute(ctx context.Context, name string, write
 		return nil
 	}
 
-	err = portal.statement.fn(ctx, NewDataWriter(ctx, portal.statement.columns, portal.formats, writer), portal.parameters)
-	if err != nil {
-		return err
-	}
-
-	return err
+	return portal.statement.fn(ctx, NewDataWriter(ctx, portal.statement.columns, portal.formats, writer), portal.parameters)
 }

command.go

@@ -17,7 +17,7 @@ import (
 )
 
 // NewErrUnimplementedMessageType is called whenever a unimplemented message
-// type is send. This error indicates to the client that the send message cannot
+// type is sent. This error indicates to the client that the sent message cannot
 // be processed at this moment in time.
 func NewErrUnimplementedMessageType(t types.ClientMessage) error {
 	err := fmt.Errorf("unimplemented client message type: %d", t)
@@ -45,7 +45,7 @@ func NewErrMultipleCommandsStatements() error {
 	return psqlerr.WithSeverity(psqlerr.WithCode(err, codes.Syntax), psqlerr.LevelError)
 }
 
-// consumeCommands consumes incoming commands send over the Postgres wire connection.
+// consumeCommands consumes incoming commands sent over the Postgres wire connection.
 // Commands consumed from the connection are returned through a go channel.
 // Responses for the given message type are written back to the client.
 // This method keeps consuming messages until the client issues a close message

conn.go

@@ -31,11 +31,11 @@ func TypeMap(ctx context.Context) *pgtype.Map {
 }
 
 // Parameters represents a parameters collection of parameter status keys and
-// their values
+// their values.
 type Parameters map[ParameterStatus]string
 
 // ParameterStatus represents a metadata key that could be defined inside a server/client
-// metadata definition
+// metadata definition.
 type ParameterStatus string
 
 // At present there is a hard-wired set of parameters for which ParameterStatus

error.go

@@ -24,7 +24,7 @@ const (
 	errFieldConstraintName errFieldType = 'n'
 )
 
-// ErrorCode writes a error message as response to a command with the given
+// ErrorCode writes an error message as response to a command with the given
 // severity and error message. A ready for query message is written back to the
 // client once the error has been written indicating the end of a command cycle.
 // https://www.postgresql.org/docs/current/static/protocol-error-fields.html

options.go

@@ -4,11 +4,10 @@ import (
 	"context"
 	"crypto/tls"
 	"crypto/x509"
+	"log/slog"
 	"regexp"
 	"strconv"
 
-	"log/slog"
-
 	"github.com/jackc/pgx/v5/pgtype"
 	"github.com/jeroenrinzema/psql-wire/pkg/buffer"
 	"github.com/lib/pq/oid"
@@ -25,9 +24,10 @@ type PreparedStatementFn func(ctx context.Context, writer DataWriter, parameters
 
 // Prepared is a small wrapper function returning a list of prepared statements.
 // More then one prepared statement could be returned within the simple query
-// protocol. An error is returned when more then one prepared statement is
-// returned in the extended query protocol.
-// https://www.postgresql.org/docs/15/protocol-flow.html#PROTOCOL-FLOW-MULTI-STATEMENT
+// protocol. An error is returned when more than one prepared statement is
+// returned in the [extended query protocol].
+//
+// [extended query protocol]: https://www.postgresql.org/docs/15/protocol-flow.html#PROTOCOL-FLOW-MULTI-STATEMENT
 func Prepared(stmts ...*PreparedStatement) PreparedStatements {
 	return stmts
 }
@@ -103,7 +103,7 @@ type CloseFn func(ctx context.Context) error
 type OptionFn func(*Server) error
 
 // Statements sets the statement cache used to cache statements for later use. By
-// default is the DefaultStatementCache used to cache prepared statements.
+// default [DefaultStatementCache] is used.
 func Statements(cache StatementCache) OptionFn {
 	return func(srv *Server) error {
 		srv.Statements = cache
@@ -112,7 +112,7 @@ func Statements(cache StatementCache) OptionFn {
 }
 
 // Portals sets the portals cache used to cache statements for later use. By
-// default is the DefaultPortalCache used to evaluate portals.
+// default [DefaultPortalCache] is used.
 func Portals(cache PortalCache) OptionFn {
 	return func(srv *Server) error {
 		srv.Portals = cache
@@ -191,7 +191,7 @@ func GlobalParameters(params Parameters) OptionFn {
 	}
 }
 
-// Logger sets the given zap logger as the default logger for the given server.
+// Logger sets the given [slog.Logger] as the logger for the given server.
 func Logger(logger *slog.Logger) OptionFn {
 	return func(srv *Server) error {
 		srv.logger = logger
@@ -209,8 +209,8 @@ func Version(version string) OptionFn {
 }
 
 // ExtendTypes provides the ability to extend the underlying connection types.
-// Types registered inside the given pgtype.ConnInfo are registered to all
-// incoming connections.
+// Types registered inside the given [github.com/jackc/pgx/v5/pgtype.Map] are
+// registered to all incoming connections.
 func ExtendTypes(fn func(*pgtype.Map)) OptionFn {
 	return func(srv *Server) error {
 		fn(srv.types)
@@ -246,11 +246,12 @@ func Session(fn SessionHandler) OptionFn {
 
 // QueryParameters represents a regex which could be used to identify and lookup
 // parameters defined inside a given query. Parameters could be defined as
-// positional parameters and un-positional parameters.
-// https://www.postgresql.org/docs/15/sql-expressions.html#SQL-EXPRESSIONS-PARAMETERS-POSITIONAL
+// [positional parameters] and non-positional parameters.
+//
+// [positional parameters]: https://www.postgresql.org/docs/15/sql-expressions.html#SQL-EXPRESSIONS-PARAMETERS-POSITIONAL
 var QueryParameters = regexp.MustCompile(`\$(\d+)|\?`)
 
-// ParseParameters attempts ot parse the parameters in the given string and
+// ParseParameters attempts to parse the parameters in the given string and
 // returns the expected parameters. This is necessary for the query protocol
 // where the parameter types are expected to be defined in the extended query protocol.
 func ParseParameters(query string) []oid.Oid {

row.go

@@ -10,14 +10,16 @@ import (
 	"github.com/lib/pq/oid"
 )
 
-// Columns represent a collection of columns
+// Columns represent a collection of columns.
 type Columns []Column
 
-// Define writes the table RowDescription headers for the given table and the
+// Define writes the table [RowDescription] headers for the given table and the
 // containing columns. The headers have to be written before any data rows could
 // be send back to the client. The given columns are encoded using the given
 // format codes. Columns could be encoded as Text or Binary. If you provide a
 // single format code, it will be applied to all columns.
+//
+// [RowDescription]: https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-ROWDESCRIPTION
 func (columns Columns) Define(ctx context.Context, writer *buffer.Writer, formats []FormatCode) error {
 	if len(columns) == 0 {
 		return nil
@@ -73,9 +75,10 @@ func (columns Columns) Write(ctx context.Context, formats []FormatCode, writer *
 	return writer.End()
 }
 
-// Column represents a table column and its attributes such as name, type and
+// Column represents a table column and its [attributes] such as name, type and
 // encode formatter.
-// https://www.postgresql.org/docs/8.3/catalog-pg-attribute.html
+//
+// [attributes]: https://www.postgresql.org/docs/8.3/catalog-pg-attribute.html
 type Column struct {
 	Table        int32  // table id
 	ID           int32  // column identifier
@@ -88,8 +91,10 @@ type Column struct {
 }
 
 // Define writes the column header values to the given writer.
-// This method is used to define a column inside RowDescription message defining
+// This method is used to define a column inside [RowDescription] message defining
 // the column type, width, and name.
+//
+// [RowDescription]: https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-ROWDESCRIPTION
 func (column Column) Define(ctx context.Context, writer *buffer.Writer, format FormatCode) {
 	writer.AddString(column.Name)
 	writer.AddNullTerminate()
@@ -116,7 +121,9 @@ func (column Column) Define(ctx context.Context, writer *buffer.Writer, format F
 
 // Write encodes the given source value using the column type definition and connection
 // info. The encoded byte buffer is added to the given write buffer. This method
-// Is used to encode values and return them inside a DataRow message.
+// Is used to encode values and return them inside a [DataRow] message.
+//
+// [DataRow]: https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-DATAROW
 func (column Column) Write(ctx context.Context, writer *buffer.Writer, format FormatCode, src any) (err error) {
 	if ctx.Err() != nil {
 		return ctx.Err()

ssl.go

@@ -1,6 +1,6 @@
 package wire
 
-// sslIdentifier represents a the bytes identifying whether the given connection
+// sslIdentifier represents the bytes identifying whether the given connection
 // supports SSL.
 type sslIdentifier []byte
 

wire.go

@@ -119,7 +119,7 @@ func (srv *Server) Serve(listener net.Listener) error {
 			ctx := context.Background()
 			err = srv.serve(ctx, conn)
 			if err != nil {
-				srv.logger.Error("an unexpected error got returned while serving a client connectio", "err", err)
+				srv.logger.Error("an unexpected error got returned while serving a client connection", "err", err)
 			}
 		}()
 	}

writer.go

@@ -21,20 +21,24 @@ type DataWriter interface {
 	// Written returns the number of rows written to the client.
 	Written() uint64
 
-	// Empty announces to the client a empty response and that no data rows should
+	// Empty announces to the client an empty response and that no data rows should
 	// be expected.
 	Empty() error
 
 	// Complete announces to the client that the command has been completed and
 	// no further data should be expected.
+	//
+	// See [CommandComplete] for the expected format for different queries.
+	//
+	// [CommandComplete]: https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-COMMANDCOMPLETE
 	Complete(description string) error
 }
 
-// ErrDataWritten is thrown when an empty result is attempted to be send to the
+// ErrDataWritten is returned when an empty result is attempted to be sent to the
 // client while data has already been written.
 var ErrDataWritten = errors.New("data has already been written")
 
-// ErrClosedWriter is thrown when the data writer has been closed
+// ErrClosedWriter is returned when the data writer has been closed.
 var ErrClosedWriter = errors.New("closed writer")
 
 // NewDataWriter constructs a new data writer using the given context and