Merge pull request #834 from go-kivik/docs

Minor doc updates

README.md

@@ -1,4 +1,4 @@
-[![Build Status](https://gitlab.com/go-kivik/kivik/badges/master/pipeline.svg)](https://gitlab.com/go-kivik/kivik/pipelines) [![Codecov](https://img.shields.io/codecov/c/github/go-kivik/kivik.svg?style=flat)](https://codecov.io/gh/go-kivik/kivik) [![Go Report Card](https://goreportcard.com/badge/github.com/go-kivik/kivik)](https://goreportcard.com/report/github.com/go-kivik/kivik) [![GoDoc](https://godoc.org/github.com/go-kivik/kivik?status.svg)](https://pkg.go.dev/github.com/go-kivik/kivik/v4) [![Website](https://img.shields.io/website-up-down-green-red/http/kivik.io.svg?label=website&colorB=007fff)](http://kivik.io)
+[![Build Status](https://gitlab.com/go-kivik/kivik/badges/master/pipeline.svg)](https://gitlab.com/go-kivik/kivik/pipelines) [![Codecov](https://img.shields.io/codecov/c/github/go-kivik/kivik.svg?style=flat)](https://codecov.io/gh/go-kivik/kivik) [![Go Report Card](https://goreportcard.com/badge/github.com/go-kivik/kivik)](https://goreportcard.com/report/github.com/go-kivik/kivik) [![Go Reference](https://pkg.go.dev/badge/github.com/go-kivik/kivik/v4.svg)](https://pkg.go.dev/github.com/go-kivik/kivik/v4) [![Website](https://img.shields.io/website-up-down-green-red/http/kivik.io.svg?label=website&colorB=007fff)](http://kivik.io)
 
 # Kivik
 
@@ -58,9 +58,8 @@ Consult the [CLI README](https://github.com/go-kivik/kivik/blob/master/cmd/kivik
 
 # Example Usage
 
-Please consult the the [package documentation](https://godoc.org/github.com/go-kivik/kivik)
-for all available API methods, and a complete usage documentation.  And for
-additional usage examples, [consult the wiki](https://github.com/go-kivik/kivik/wiki/Usage-Examples).
+Please consult the the [package documentation](https://pkg.go.dev/github.com/go-kivik/kivik/v4)
+for all available API methods, and a complete usage documentation, and usage examples.
 
 ```go
 package main

couchdb/README.md

@@ -1,4 +1,4 @@
-[![Build Status](https://travis-ci.org/go-kivik/couchdb.svg?branch=master)](https://travis-ci.org/go-kivik/couchdb) [![Codecov](https://img.shields.io/codecov/c/github/go-kivik/couchdb.svg?style=flat)](https://codecov.io/gh/go-kivik/couchdb) [![GoDoc](https://godoc.org/github.com/go-kivik/couchdb?status.svg)](http://godoc.org/github.com/go-kivik/couchdb)
+[![Go Reference](https://pkg.go.dev/badge/github.com/go-kivik/kivik/v4/couchdb.svg)](https://pkg.go.dev/github.com/go-kivik/kivik/v4/couchdb)
 
 # Kivik CouchDB
 
@@ -7,11 +7,9 @@ CouchDB driver for [Kivik](https://github.com/go-kivik/kivik).
 ## Usage
 
 This package provides an implementation of the
-[`github.com/go-kivik/kivik/v4/driver`](http://godoc.org/github.com/go-kivik/kivik/driver)
+[`github.com/go-kivik/kivik/v4/driver`](http://pkg.go.dev/github.com/go-kivik/kivik/v4/driver)
 interface. You must import the driver and can then use the full
-[`Kivik`](http://godoc.org/github.com/go-kivik/kivik) API. Please consult the
-[Kivik wiki](https://github.com/go-kivik/kivik/wiki) for complete documentation
-and coding examples.
+[`Kivik`](http://pkg.go.dev/github.com/go-kivik/kivik/v4) API.
 
 ```go
 package main

db_example_test.go

@@ -14,6 +14,7 @@ package kivik_test
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
 
 	kivik "github.com/go-kivik/kivik/v4"
@@ -103,22 +104,83 @@ func ExampleDB_updateView() {
 }
 
 func ExampleDB_query() {
-	rows := db.Query(context.TODO(), "_design/foo", "_view/bar", kivik.Params(map[string]interface{}{
+	rs := db.Query(context.TODO(), "_design/foo", "_view/bar", kivik.Params(map[string]interface{}{
 		"startkey": `"foo"`,                           // Quotes are necessary so the
 		"endkey":   `"foo` + kivik.EndKeySuffix + `"`, // key is a valid JSON object
 	}))
-	if err := rows.Err(); err != nil {
-		panic(err)
+	defer rs.Close()
+	for rs.Next() {
+		var doc interface{}
+		if err := rs.ScanDoc(&doc); err != nil {
+			panic(err)
+		}
+		/* do something with doc */
 	}
-	for rows.Next() {
+	if rs.Err() != nil {
+		panic(rs.Err())
+	}
+}
+
+func ExampleDB_query_compound_key() {
+	rs := db.Query(context.TODO(), "_design/foo", "_view/bar", kivik.Params(map[string]interface{}{
+		"startkey": []string{"foo", "bar"},
+		"endkey":   []string{"foo", "bar" + kivik.EndKeySuffix},
+	}))
+	defer rs.Close()
+	for rs.Next() {
 		var doc interface{}
-		if err := rows.ScanDoc(&doc); err != nil {
+		if err := rs.ScanDoc(&doc); err != nil {
 			panic(err)
 		}
 		/* do something with doc */
 	}
-	if rows.Err() != nil {
-		panic(rows.Err())
+	if rs.Err() != nil {
+		panic(rs.Err())
+	}
+}
+
+func ExampleDB_query_literal_JSON_keys() {
+	rs := db.Query(context.TODO(), "_design/foo", "_view/bar", kivik.Param(
+		"startkey", json.RawMessage(`{"foo":true}`),
+	))
+	defer rs.Close()
+	for rs.Next() {
+		var doc interface{}
+		if err := rs.ScanDoc(&doc); err != nil {
+			panic(err)
+		}
+		/* do something with doc */
+	}
+	if rs.Err() != nil {
+		panic(rs.Err())
+	}
+}
+
+func ExampleDB_multiple_queries() {
+	rs := db.Query(context.TODO(), "_design/foo", "_view/bar", kivik.Param(
+		"queries", []interface{}{
+			map[string]interface{}{
+				"startkey":     []string{"foo", "bar"},
+				"endkey":       []string{"foo", "bar" + kivik.EndKeySuffix},
+				"include_docs": true,
+			},
+			map[string]interface{}{
+				"startkey":     []string{"baz", "bar"},
+				"endkey":       []string{"baz", "bar" + kivik.EndKeySuffix},
+				"include_docs": true,
+			},
+		}))
+	defer rs.Close()
+	var rsIndex int
+	for rs.NextResultSet() {
+		rsIndex++
+		for rs.Next() {
+			var doc interface{}
+			if err := rs.ScanDoc(&doc); err != nil {
+				panic(err)
+			}
+			/* do something with doc */
+		}
 	}
 }
 

doc.go

@@ -31,16 +31,16 @@ The kivik driver system is modeled after the standard library's `sql` and
 the different database models implemented by SQL and NoSQL databases such as
 CouchDB.
 
+The most methods, including those on [Client] and [DB] are safe to call
+concurrently, unless otherwise noted.
+
 # Working with JSON
 
 CouchDB stores JSON, so Kivik translates Go data structures to and from JSON as
 necessary. The conversion from Go data types to JSON, and vice versa, is
 handled automatically according to the rules and behavior described in the
 documentation for the standard library's [encoding/json] package.
 
-One would be well-advised to become familiar with using `json` struct field
-tags [encoding/json.Marshal] when working with JSON documents.
-
 # Options
 
 Most client and database methods take optional arguments of the type [Option].

mockdb/README.md

@@ -1,3 +1,5 @@
+[![Go Reference](https://pkg.go.dev/badge/github.com/go-kivik/kivik/v4/x/mockdb.svg)](https://pkg.go.dev/github.com/go-kivik/kivik/v4/x/mockdb)
+
 # MockDB
 
 Package **mockdb** is a mock library implementing a Kivik driver.

pouchdb/README.md

@@ -1,4 +1,4 @@
-[![Build Status](https://travis-ci.org/go-kivik/pouchdb.svg?branch=master)](https://travis-ci.org/go-kivik/pouchdb)  [![GoDoc](https://godoc.org/github.com/go-kivik/pouchdb?status.svg)](http://godoc.org/github.com/go-kivik/pouchdb)
+[![Go Reference](https://pkg.go.dev/badge/github.com/go-kivik/kivik/v4/pouchdb.svg)](https://pkg.go.dev/github.com/go-kivik/kivik/v4/pouchdb)
 
 # Kivik PouchDB
 
@@ -17,11 +17,9 @@ with Kivik as an example.
 ## Usage
 
 This package provides an implementation of the
-[`github.com/go-kivik/kivik/driver`](http://godoc.org/github.com/go-kivik/kivik/driver)
+[`github.com/go-kivik/kivik/v4/driver`](http://pkg.go.dev/github.com/go-kivik/kivik/v4/driver)
 interface. You must import the driver and can then use the full
-[`Kivik`](http://godoc.org/github.com/go-kivik/kivik) API. Please consult the
-[Kivik wiki](https://github.com/go-kivik/kivik/wiki) for complete documentation
-and coding examples.
+[`Kivik`](http://pkg.go.dev/github.com/go-kivik/kivik/v4) API.
 
 ```go
 // +build js

x/fsdb/README.md

@@ -1,4 +1,4 @@
-[![GoDoc](https://godoc.org/github.com/go-kivik/kivik/v4/x/fsdb?status.svg)](http://godoc.org/github.com/go-kivik/kivik/v4/x/fsdb)
+[![Go Reference](https://pkg.go.dev/badge/github.com/go-kivik/kivik/v4/x/fsdb.svg)](https://pkg.go.dev/github.com/go-kivik/kivik/v4/x/fsdb)
 
 # Kivik FSDB
 
@@ -13,11 +13,9 @@ This is very much a work in progress. Things are expected to change quickly.
 ## Usage
 
 This package provides an implementation of the
-[`github.com/go-kivik/kivik/driver`](http://godoc.org/github.com/go-kivik/kivik/driver)
+[`github.com/go-kivik/kivik/driver`](http://pkg.go.dev/github.com/go-kivik/kivik/v4/driver)
 interface. You must import the driver and can then use the full
-[`Kivik`](http://godoc.org/github.com/go-kivik/kivik) API. Please consult the
-[Kivik wiki](https://github.com/go-kivik/kivik/wiki) for complete documentation
-and coding examples.
+[`Kivik`](http://pkg.go.dev/github.com/go-kivik/kivik/v4) API.
 
 ```go
 package main

x/mango/README.md

@@ -1,4 +1,4 @@
-[![GoDoc](https://godoc.org/github.com/go-kivik/kivik/v4/x/mango?status.svg)](http://godoc.org/github.com/go-kivik/kivik/v4/x/mango)
+[![Go Reference](https://pkg.go.dev/badge/github.com/go-kivik/kivik/v4/x/mango.svg)](https://pkg.go.dev/github.com/go-kivik/kivik/v4/x/mango)
 
 # Mango
 

x/memorydb/README.md

@@ -1,4 +1,4 @@
-[![GoDoc](https://godoc.org/github.com/go-kivik/kivik/v4/x/memorydb?status.svg)](http://godoc.org/github.com/go-kivik/kivik/v4/x/memorydb)
+[![Go Reference](https://pkg.go.dev/badge/github.com/go-kivik/kivik/v4/x/memorydb.svg)](https://pkg.go.dev/github.com/go-kivik/kivik/v4/x/memorydb)
 
 # Kivik MemoryDB
 
@@ -9,11 +9,9 @@ This driver stores documents in memory only, and is intended for testing purpose
 ## Usage
 
 This package provides an implementation of the
-[`github.com/go-kivik/kivik/driver`](http://godoc.org/github.com/go-kivik/kivik/driver)
+[`github.com/go-kivik/kivik/driver`](http://pkg.go.dev/github.com/go-kivik/kivik/v4/driver)
 interface. You must import the driver and can then use the full
-[`Kivik`](http://godoc.org/github.com/go-kivik/kivik) API. Please consult the
-[Kivik wiki](https://github.com/go-kivik/kivik/wiki) for complete documentation
-and coding examples.
+[`Kivik`](http://pkg.go.dev/github.com/go-kivik/kivik/v4) API.
 
 ```go
 package main