massive documentation overhaul

bind.go

@@ -8,6 +8,7 @@ import (
 	"unicode"
 )
 
+// Bindvar types supported by sqlx's Rebind & BindMap/Struct functions.
 const (
 	UNKNOWN = iota
 	QUESTION
@@ -52,8 +53,9 @@ func Rebind(bindType int, query string) string {
 	return string(rqb)
 }
 
-// Bind a named parameter query with fields from a struct argument
-// Use of reflect here makes this
+// Bind a named parameter query with fields from a struct argument.  The rules
+// for binding field names to parameter names follow the same conventions as
+// for StructScan, including obeying the `db` struct tags.
 func BindStruct(bindType int, query string, arg interface{}) (string, []interface{}, error) {
 	arglist := make([]interface{}, 0, 5)
 	t, err := BaseStructType(reflect.TypeOf(arg))
@@ -80,8 +82,7 @@ func BindStruct(bindType int, query string, arg interface{}) (string, []interfac
 	return BindMap(bindType, query, argmap)
 }
 
-// Bind a named parameter query with a map of arguments to a regular positional
-// bindvar query and return arguments for the new query in a slice.
+// Bind a named parameter query with a map of arguments.
 func BindMap(bindType int, query string, args map[string]interface{}) (string, []interface{}, error) {
 	arglist := make([]interface{}, 0, 5)
 	// In all likelihood, the rebound query will be shorter
@@ -150,6 +151,11 @@ func BindMap(bindType int, query string, args map[string]interface{}) (string, [
 	return string(rebound), arglist, nil
 }
 
+// Experimental implementation of Rebind which uses a bytes.Buffer.  The code is
+// much simpler and should be more resistant to odd unicode, but it is twice as
+// slow.  Kept here for benchmarking purposes and to possibly replace Rebind if
+// problems arise with its somewhat naive handling of unicode.
+
 func rebindBuff(bindType int, query string) string {
 	if bindType != DOLLAR {
 		return query

doc.go

@@ -1,37 +1,12 @@
 // General purpose extensions to database/sql
 //
-// sqlx is intended to seamlessly wrap database/sql and provide some convenience
-// methods which range from basic common error handling techniques to complex
-// reflect-base Scan extensions.  Replacing `sql.Open` with `sqlx.Open` should
-// provide access to most of the features within sqlx while not changing the
-// interface used by any existing code.
-//
-// sqlx introduces the following concepts which are accessible wherever they
-// make sense:
-//
-// The addition of a mnemonic set of "Exec" functions:
-//
-//	Execv - log.Println errors, return (rows, err)
-//	Execl - log.Println errors, return only rows
-//	Execp - panic(err) on error
-//	Execf - log.Fatal(err) on error
-// 	MustExec - same as Execp
-//
-// The addition of a "StructScan" function, which takes an the result from a
-// query and a struct slice and automatically scans each row as a struct.
-//
-// The addition of a set of "Select" functions, which combine Query and
-// StructScan and have "f" and "v" error handling variantes like Exec.
-//
-// The addition of a "Get" function, which is to "QueryRow" what "Select" is
-// to "Query", and will return a special Row that can StructScan.
-//
-// The addition of Named Queries, accessible via either struct arguments or
-// via map arguments
-//
-// A "LoadFile" convenience function which executes the queries in a file.
-//
-// A "Connect" function, which combines "Open" and "Ping", and panicing variants
-// of Connect and Begin: MustConnect, MustBegin.
+// sqlx is intended to seamlessly wrap database/sql and provide convenience
+// methods which are useful in the development of database driven applications.
+// None of the underlying database/sql methods are changed, instead all extended
+// behavior is implemented through new methods defined on wrapper types.
+//
+// sqlx adds struct scanning, named queries, query rebinding between drivers,
+// convenient shorthand for common error handling, from-file query execution,
+// and more.
 //
 package sqlx