Update doc.

backup.go

@@ -16,6 +16,7 @@ import (
 )
 
 // Backup/Copy the content of one database (source) to another (destination).
+// The database name is "main", "temp", or the name specified in an ATTACH statement.
 // Example:
 //	bck, err := sqlite.NewBackup(dst, "main", src, "main")
 //	// check err

hook.go

@@ -56,7 +56,7 @@ func goXRollbackHook(udp unsafe.Pointer) {
 	arg.f(arg.udp)
 }
 
-// Rollback notification callback
+// Register a callback to be invoked each time a transaction is rolled back by this database connection.
 // (See http://sqlite.org/c3ref/commit_hook.html)
 func (c *Conn) RollbackHook(f RollbackHook, udp interface{}) {
 	if f == nil {
@@ -82,7 +82,7 @@ func goXUpdateHook(udp unsafe.Pointer, action int, dbName, tableName *C.char, ro
 	arg.f(arg.udp, Action(action), C.GoString(dbName), C.GoString(tableName), int64(rowId))
 }
 
-// Data change notification callbacks
+// Register a callback to be invoked each time a row is updated, inserted or deleted using this database connection.
 // (See http://sqlite.org/c3ref/update_hook.html)
 func (c *Conn) UpdateHook(f UpdateHook, udp interface{}) {
 	if f == nil {

sqlite.go

@@ -283,7 +283,7 @@ func (c *Conn) EnableExtendedResultCodes(b bool) error {
 // Don't use it with SELECT or anything that returns data.
 //
 // Example:
-//	err := db.Exec("CREATE TABLE test(id INTEGER PRIMARY KEY NOT NULL, name TEXT NOT NULL)")
+//	err := db.Exec("CREATE TABLE test(id INTEGER PRIMARY KEY NOT NULL, name TEXT NOT NULL); -- ...")
 //
 func (c *Conn) Exec(cmd string, args ...interface{}) error {
 	for len(cmd) > 0 {

stmt.go

@@ -68,19 +68,20 @@ func (s *Stmt) specificError(msg string, a ...interface{}) error {
 
 // SQL statement
 type Stmt struct {
-	c      *Conn
-	stmt   *C.sqlite3_stmt
-	sql string
-	tail   string
-	columnCount int
-	cols   map[string]int // cached columns index by name
+	c                  *Conn
+	stmt               *C.sqlite3_stmt
+	sql                string
+	tail               string
+	columnCount        int
+	cols               map[string]int // cached columns index by name
 	bindParameterCount int
-	params map[string]int // cached parameter index by name
+	params             map[string]int // cached parameter index by name
 	// Enable type check in Scan methods
 	CheckTypeMismatch bool
 }
 
-// Compile an SQL statement and optionally bind values
+// Compile an SQL statement and optionally bind values.
+// If an error occurs while binding values, the statement is returned (not finalized).
 // Example:
 //	stmt, err := db.Prepare("SELECT 1 where 1 = ?", 1)
 //	if err != nil {
@@ -115,8 +116,9 @@ func (c *Conn) Prepare(cmd string, args ...interface{}) (*Stmt, error) {
 	return s, nil
 }
 
-// One-step statement execution
+// One-step statement execution.
 // Don't use it with SELECT or anything that returns data.
+// The Stmt is reset at each call.
 // (See http://sqlite.org/c3ref/bind_blob.html, http://sqlite.org/c3ref/step.html)
 func (s *Stmt) Exec(args ...interface{}) error {
 	err := s.Bind(args...)
@@ -136,6 +138,7 @@ func (s *Stmt) exec() error {
 
 // Like Exec but returns the number of rows that were changed or inserted or deleted.
 // Don't use it with SELECT or anything that returns data.
+// The Stmt is reset at each call.
 func (s *Stmt) ExecDml(args ...interface{}) (int, error) {
 	err := s.Exec(args...)
 	if err != nil {
@@ -146,6 +149,7 @@ func (s *Stmt) ExecDml(args ...interface{}) (int, error) {
 
 // Like ExecDml but returns the autoincremented rowid.
 // Don't use it with SELECT or anything that returns data.
+// The Stmt is reset at each call.
 func (s *Stmt) Insert(args ...interface{}) (int64, error) {
 	n, err := s.ExecDml(args...)
 	if err != nil {
@@ -211,7 +215,8 @@ func (s *Stmt) BindParameterIndex(name string) (int, error) {
 	return index, nil
 }
 
-// Name of a host parameter (not cached)
+// Return the name of a wildcard parameter. (not cached)
+// Return "" if the index is out of range or if the wildcard is unnamed.
 // The first host parameter has an index of 1, not 0.
 // (See http://sqlite.org/c3ref/bind_parameter_name.html)
 func (s *Stmt) BindParameterName(i int) (string, error) {
@@ -335,7 +340,8 @@ func (s *Stmt) Next() (bool, error) {
 	return false, nil
 }
 
-// Reset a prepared statement
+// Terminate the current execution of an SQL statement
+// and reset it back to its starting state so that it can be reused.
 // (See http://sqlite.org/c3ref/reset.html)
 func (s *Stmt) Reset() error {
 	return s.error(C.sqlite3_reset(s.stmt))
@@ -347,7 +353,7 @@ func (s *Stmt) ClearBindings() error {
 	return s.error(C.sqlite3_clear_bindings(s.stmt))
 }
 
-// Number of columns in a result set (with or without row)
+// Return the number of columns in the result set for the statement (with or without row)
 // (See http://sqlite.org/c3ref/column_count.html)
 func (s *Stmt) ColumnCount() int {
 	if s.columnCount == -1 {
@@ -356,14 +362,14 @@ func (s *Stmt) ColumnCount() int {
 	return s.columnCount
 }
 
-// Number of columns in a result set
+// Return the number of values available from the current row of the currently executing statement.
 // Same as ColumnCount() except when there is no (more) row, it returns 0
 // (See http://sqlite.org/c3ref/data_count.html)
 func (s *Stmt) DataCount() int {
 	return int(C.sqlite3_data_count(s.stmt))
 }
 
-// Column name in a result set (not cached)
+// Return the name of the Nth column of the result set returned by the SQL statement. (not cached)
 // The leftmost column is number 0.
 // (See http://sqlite.org/c3ref/column_name.html)
 func (s *Stmt) ColumnName(index int) string {
@@ -371,7 +377,7 @@ func (s *Stmt) ColumnName(index int) string {
 	return C.GoString(C.sqlite3_column_name(s.stmt, C.int(index)))
 }
 
-// Column names in a result set (not cached)
+// Return the name of the columns of the result set returned by the SQL statement. (not cached)
 func (s *Stmt) ColumnNames() []string {
 	count := s.ColumnCount()
 	names := make([]string, count)
@@ -490,7 +496,7 @@ func (s *Stmt) Scan(args ...interface{}) error {
 	return nil
 }
 
-// Retrieve statement SQL
+// Return the SQL associated with a prepared statement.
 // (See http://sqlite.org/c3ref/sql.html)
 func (s *Stmt) SQL() string {
 	if s.sql == "" {
@@ -695,6 +701,7 @@ func (s *Stmt) ScanText(index int) (value string, isNull bool) {
 // The leftmost column/index is number 0.
 // Returns true when column is null.
 // (See sqlite3_column_int: http://sqlite.org/c3ref/column_blob.html)
+// TODO Factorize with ScanByte, ScanBool
 func (s *Stmt) ScanInt(index int) (value int, isNull bool, err error) {
 	ctype := s.ColumnType(index)
 	if ctype == Null {
@@ -858,7 +865,7 @@ func (s *Stmt) checkTypeMismatch(source, target Type) error {
 	return nil
 }
 
-// Determine if a prepared statement has been reset
+// Return true if the prepared statement is in need of being reset.
 // (See http://sqlite.org/c3ref/stmt_busy.html)
 func (s *Stmt) Busy() bool {
 	return C.sqlite3_stmt_busy(s.stmt) != 0
@@ -881,7 +888,7 @@ func (s *Stmt) Conn() *Conn {
 	return s.c
 }
 
-// Determine if an SQL statement writes the database
+// Return true if the prepared statement is guaranteed to not modify the database.
 // (See http://sqlite.org/c3ref/stmt_readonly.html)
 func (s *Stmt) ReadOnly() bool {
 	return C.sqlite3_stmt_readonly(s.stmt) == 1

trace.go

@@ -39,7 +39,7 @@ func goXTrace(udp unsafe.Pointer, sql *C.char) {
 	arg.f(arg.udp, C.GoString(sql))
 }
 
-// Tracing function
+// Register or clear a trace function.
 // (See sqlite3_trace, http://sqlite.org/c3ref/profile.html)
 func (c *Conn) Trace(f Tracer, udp interface{}) {
 	if f == nil {
@@ -66,7 +66,7 @@ func goXProfile(udp unsafe.Pointer, sql *C.char, nanoseconds C.sqlite3_uint64) {
 	arg.f(arg.udp, C.GoString(sql), uint64(nanoseconds))
 }
 
-// Profiling Function
+// Register or clear a profile function.
 // (See sqlite3_profile, http://sqlite.org/c3ref/profile.html)
 func (c *Conn) Profile(f Profiler, udp interface{}) {
 	if f == nil {
@@ -142,7 +142,7 @@ func goXAuth(udp unsafe.Pointer, action int, arg1, arg2, dbName, triggerName *C.
 	return C.int(result)
 }
 
-// Compile-time authorization callbacks
+// Set or clear the access authorization function.
 // (See http://sqlite.org/c3ref/set_authorizer.html)
 func (c *Conn) SetAuthorizer(f Authorizer, udp interface{}) error {
 	if f == nil {
@@ -199,6 +199,7 @@ func goXProgress(udp unsafe.Pointer) C.int {
 }
 
 // Query progress callbacks
+// The progress callback will be invoked every numOps opcodes.
 // (See http://sqlite.org/c3ref/progress_handler.html)
 func (c *Conn) ProgressHandler(f ProgressHandler, numOps int, udp interface{}) {
 	if f == nil {
@@ -220,7 +221,7 @@ const (
 	STMTSTATUS_AUTOINDEX     StmtStatus = C.SQLITE_STMTSTATUS_AUTOINDEX
 )
 
-// Prepared statement status
+// Return the value of a status counter for a prepared statement
 // (See http://sqlite.org/c3ref/stmt_status.html)
 func (s *Stmt) Status(op StmtStatus, reset bool) int {
 	return int(C.sqlite3_stmt_status(s.stmt, C.int(op), btocint(reset)))