database/sql: document args, add a couple examples

Fixes #3460

R=golang-dev, alex.brainman
CC=golang-dev
https://golang.org/cl/7096046

src/pkg/database/sql/example_test.go

@@ -0,0 +1,45 @@
+// Copyright 2013 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package sql_test
+
+import (
+	"database/sql"
+	"fmt"
+	"log"
+)
+
+var db *sql.DB
+
+func ExampleDB_Query() {
+	age := 27
+	rows, err := db.Query("SELECT name FROM users WHERE age=?", age)
+	if err != nil {
+		log.Fatal(err)
+	}
+	for rows.Next() {
+		var name string
+		if err := rows.Scan(&name); err != nil {
+			log.Fatal(err)
+		}
+		fmt.Printf("%s is %d\n", name, age)
+	}
+	if err := rows.Err(); err != nil {
+		log.Fatal(err)
+	}
+}
+
+func ExampleDB_QueryRow() {
+	id := 123
+	var username string
+	err := db.QueryRow("SELECT username FROM users WHERE id=?", id).Scan(&username)
+	switch {
+	case err == sql.ErrNoRows:
+		log.Printf("No user with that ID.")
+	case err != nil:
+		log.Fatal(err)
+	default:
+		fmt.Printf("Username is %s\n", username)
+	}
+}

src/pkg/database/sql/sql.go

@@ -373,6 +373,7 @@ func (db *DB) exec(query string, args []interface{}) (res Result, err error) {
 }
 
 // Query executes a query that returns rows, typically a SELECT.
+// The args are for any placeholder parameters in the query.
 func (db *DB) Query(query string, args ...interface{}) (*Rows, error) {
 	stmt, err := db.Prepare(query)
 	if err != nil {