From 6973dcc06c4436274c371747718df8267b54a6c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Olivier=20Mengu=C3=A9?= Date: Sun, 5 Nov 2023 00:25:30 +0100 Subject: [PATCH] doc: refer to database/sql via the 'sql' shortcut In stmt.go, database/sql wasn't imported. So I had to do a fake variable declaration jsut to make a reference to one database/sql symbol to have an import not cleared by goimports. Also, fix '*' being external to the brackets in godoc: // *[database/sql.Rows] -> [*sql.Rows] --- scan.go | 6 +++--- stmt.go | 27 +++++++++++++++------------ utils.go | 4 ++-- 3 files changed, 20 insertions(+), 17 deletions(-) diff --git a/scan.go b/scan.go index 4621742..25ab99e 100644 --- a/scan.go +++ b/scan.go @@ -21,11 +21,11 @@ import ( "reflect" ) -// Scan allows to define a function that will scan one row from an *[database/sql.Rows]. +// Scan allows to define a function that will scan one row from an [*sql.Rows]. // // The signature of the function defines how the column values are retrieved into variables. // Two styles are available: -// - as pointer variables (like [database/sql.Rows.Scan]): func (rows *sql.Rows, pval1 *int, pval2 *string) error +// - as pointer variables (like [sql.Rows.Scan]): func (rows *sql.Rows, pval1 *int, pval2 *string) error // - as returned values (implies copies): func (rows *sql.Rows) (val1 int, val2 string, err error) func Scan(fnPtr interface{}) { vPtr := reflect.ValueOf(fnPtr) @@ -94,7 +94,7 @@ func Scan(fnPtr interface{}) { vPtr.Elem().Set(reflect.MakeFunc(fnType, fn)) } -// ForEach iterates an *[database/sql.Rows], scans the values of the row and calls the given callback function with the values. +// ForEach iterates an [*sql.Rows], scans the values of the row and calls the given callback function with the values. // // The callback receives the scanned columns values as arguments and may return an error or a bool (false) to stop iterating. // diff --git a/stmt.go b/stmt.go index 416cb9c..47049fd 100644 --- a/stmt.go +++ b/stmt.go @@ -18,18 +18,21 @@ package sqlfunc import ( "context" + "database/sql" "reflect" ) -// Exec prepares an SQL statement and creates a function wrapping [database/sql.Stmt.ExecContext]. +var _ *sql.DB // Fake var just to have database/sql imported for go doc + +// Exec prepares an SQL statement and creates a function wrapping [sql.Stmt.ExecContext]. // // fnPtr is a pointer to a func variable. The function signature tells how it will be called. // // The first argument is a [context.Context]. -// If a *[database/sql.Tx] is given as the second argument, the statement will be localized to the transaction (using [database/sql.Tx.StmtContext]). -// The following arguments will be given as arguments to [database/sql.Stmt.ExecContext]. +// If a [*sql.Tx] is given as the second argument, the statement will be localized to the transaction (using [sql.Tx.StmtContext]). +// The following arguments will be given as arguments to [sql.Stmt.ExecContext]. // -// The function will return an [database/sql.Result] and an error. +// The function will return an [sql.Result] and an error. // // The returned func 'close' must be called once the statement is not needed anymore. // @@ -109,15 +112,15 @@ func Exec(ctx context.Context, db PrepareConn, query string, fnPtr interface{}) return stmt.Close, nil } -// QueryRow prepares an SQL statement and creates a function wrapping [database/sql.Stmt.QueryRowContext] and [database/sql.Row.Scan]. +// QueryRow prepares an SQL statement and creates a function wrapping [sql.Stmt.QueryRowContext] and [sql.Row.Scan]. // // fnPtr is a pointer to a func variable. The function signature tells how it will be called. // // The first argument is a [context.Context]. -// If a *[database/sql.Tx] is given as the second argument, the statement will be localized to the transaction (using [database/sql.Tx.StmtContext]). -// The following arguments will be given as arguments to [database/sql.Stmt.QueryRowContext]. +// If a [*sql.Tx] is given as the second argument, the statement will be localized to the transaction (using [sql.Tx.StmtContext]). +// The following arguments will be given as arguments to [sql.Stmt.QueryRowContext]. // -// The function will return values scanned from the [database/sql.Row] and an error. +// The function will return values scanned from the [sql.Row] and an error. // // The returned func 'close' must be called once the statement is not needed anymore. func QueryRow(ctx context.Context, db PrepareConn, query string, fnPtr interface{}) (close func() error, err error) { @@ -188,15 +191,15 @@ func QueryRow(ctx context.Context, db PrepareConn, query string, fnPtr interface return stmt.Close, nil } -// Query prepares an SQL statement and creates a function wrapping [database/sql.Stmt.QueryContext]. +// Query prepares an SQL statement and creates a function wrapping [sql.Stmt.QueryContext]. // // fnPtr is a pointer to a func variable. The function signature tells how it will be called. // // The first argument is a [context.Context]. -// If an *[database/sql.Tx] is given as the second argument, the statement will be localized to the transaction (using [database/sql.Tx.StmtContext]). -// The following arguments will be given as arguments to [database/sql.Stmt.QueryRowContext]. +// If an [*sql.Tx] is given as the second argument, the statement will be localized to the transaction (using [sql.Tx.StmtContext]). +// The following arguments will be given as arguments to [sql.Stmt.QueryRowContext]. // -// The function will return an *[database/sql.Rows] and an error. +// The function will return an [*sql.Rows] and an error. // // The returned func 'close' must be called once the statement is not needed anymore. func Query(ctx context.Context, db PrepareConn, query string, fnPtr interface{}) (close func() error, err error) { diff --git a/utils.go b/utils.go index c5f7301..8c2edc3 100644 --- a/utils.go +++ b/utils.go @@ -22,12 +22,12 @@ import ( "reflect" ) -// PrepareConn is a subset of *[database/sql.DB], *[database/sql.Conn] or *[database/sql.Tx]. +// PrepareConn is a subset of [*database/sql.DB], [*database/sql.Conn] or [*database/sql.Tx]. type PrepareConn interface { PrepareContext(ctx context.Context, query string) (*sql.Stmt, error) } -// txStmt is a subset of *[database/sql.Tx]. +// txStmt is a subset of [*database/sql.Tx]. type txStmt interface { StmtContext(ctx context.Context, stmt *sql.Stmt) *sql.Stmt }