Replace inline doc examples with proper godoc examples

Author: zombiezen

example_test.go

@@ -9,6 +9,7 @@ import (
 	"fmt"
 	"io"
 	"regexp"
+	"time"
 
 	"zombiezen.com/go/sqlite"
 	"zombiezen.com/go/sqlite/sqlitex"
@@ -77,7 +78,8 @@ func ExampleConn_SetInterrupt() {
 
 	// You can use the Done() channel from a context to set deadlines and timeouts
 	// on queries.
-	ctx := context.TODO()
+	ctx, cancel := context.WithTimeout(context.TODO(), 100*time.Millisecond)
+	defer cancel()
 	conn.SetInterrupt(ctx.Done())
 }
 

sqlite.go

@@ -250,12 +250,6 @@ func (c *Conn) CheckReset() string {
 // Subsequent uses of the connection will return SQLITE_INTERRUPT
 // errors until doneCh is reset with a subsequent call to SetInterrupt.
 //
-// Typically, doneCh is provided by the Done method on a context.Context.
-// For example, a timeout can be associated with a connection session:
-//
-//	ctx := context.WithTimeout(context.Background(), 100*time.Millisecond)
-//	conn.SetInterrupt(ctx.Done())
-//
 // Any busy statements at the time SetInterrupt is called will be reset.
 //
 // SetInterrupt returns the old doneCh assigned to the connection.

sqlitex/example_test.go

@@ -4,6 +4,7 @@
 package sqlitex_test
 
 import (
+	"context"
 	"fmt"
 
 	"zombiezen.com/go/sqlite"
@@ -45,3 +46,34 @@ func ExampleExecute() {
 	// Output:
 	// [a1] [1]
 }
+
+func ExampleSave() {
+	doWork := func(conn *sqlite.Conn) (err error) {
+		defer sqlitex.Save(conn)(&err)
+
+		// ... do work in the transaction
+		return nil
+	}
+	_ = doWork
+}
+
+func ExamplePool() {
+	// Open a pool.
+	dbpool, err := sqlitex.Open("foo.db", 0, 10)
+	if err != nil {
+		// handle err
+	}
+	defer func() {
+		if err := dbpool.Close(); err != nil {
+			// handle err
+		}
+	}()
+
+	// While handling a request:
+	ctx := context.TODO()
+	conn := dbpool.Get(ctx)
+	if conn == nil {
+		// handle err
+	}
+	defer dbpool.Put(conn)
+}

sqlitex/pool.go

@@ -26,23 +26,7 @@ import (
 )
 
 // Pool is a pool of SQLite connections.
-//
 // It is safe for use by multiple goroutines concurrently.
-//
-// Typically, a goroutine that needs to use an SQLite *Conn
-// Gets it from the pool and defers its return:
-//
-//	conn := dbpool.Get(nil)
-//	defer dbpool.Put(conn)
-//
-// As Get may block, a context can be used to return if a task
-// is cancelled. In this case the Conn returned will be nil:
-//
-//	conn := dbpool.Get(ctx)
-//	if conn == nil {
-//		return context.Canceled
-//	}
-//	defer dbpool.Put(conn)
 type Pool struct {
 	free   chan *sqlite.Conn
 	closed chan struct{}

sqlitex/savepoint.go

@@ -31,14 +31,6 @@ import (
 // RELEASE or ROLLBACK depending on whether the parameter *error
 // points to a nil or non-nil error. This is designed to be deferred.
 //
-// Example:
-//
-//	func doWork(conn *sqlite.Conn) (err error) {
-//		defer sqlitex.Save(conn)(&err)
-//
-//		// ... do work in the transaction
-//	}
-//
 // https://www.sqlite.org/lang_savepoint.html
 func Save(conn *sqlite.Conn) (releaseFn func(*error)) {
 	name := "sqlitex.Save" // safe as names can be reused