database/sql: rename NamedParam to NamedArg and Param to Named

Be consistent with the argument names already provided. Also
parameter is the variable, argument is the value.

Fixes #18099

Change-Id: Idb3f4e9ffc214036c721ddb4f614ec6c95bb7778
Reviewed-on: https://go-review.googlesource.com/33660
Run-TryBot: Russ Cox <rsc@golang.org>
Reviewed-by: Russ Cox <rsc@golang.org>

1 files changed, 18 insertions, 7 deletions

diff --git a/src/database/sql/sql.go b/src/database/sql/sql.go
index 4ef0fa7221..a620707b2d 100644
--- a/src/database/sql/sql.go
+++ b/src/database/sql/sql.go
@@ -69,9 +69,9 @@ func Drivers() []string {
 	return list
 }
 
-// NamedParam may be passed into query parameter arguments to associate
-// a named placeholder with a value.
-type NamedParam struct {
+// A NamedArg used as an argument to Query or Exec
+// binds to the corresponding named parameter in the SQL statement.
+type NamedArg struct {
 	_Named_Fields_Required struct{}
 
 	// Name of the parameter placeholder. If empty the ordinal position in the
@@ -83,13 +83,24 @@ type NamedParam struct {
 	Value interface{}
 }
 
-// Param provides a more concise way to create NamedParam values.
-func Param(name string, value interface{}) NamedParam {
+// Named provides a more concise way to create NamedArg values.
+//
+// Example usage:
+//
+//     db.ExecContext(ctx, `
+//         delete from Invoice
+//         where
+//             TimeCreated < @end
+//             and TimeCreated >= @start;`,
+//         sql.Named("start", startTime),
+//         sql.Named("end", endTime),
+//     )
+func Named(name string, value interface{}) NamedArg {
 	// This method exists because the go1compat promise
 	// doesn't guarantee that structs don't grow more fields,
 	// so unkeyed struct literals are a vet error. Thus, we don't
-	// want to encourage sql.NamedParam{name, value}.
-	return NamedParam{Name: name, Value: value}
+	// want to allow sql.NamedArg{name, value}.
+	return NamedArg{Name: name, Value: value}
 }
 
 // IsolationLevel is the transaction isolation level stored in Context.