add comments for database

database/driver.go

@@ -1,3 +1,7 @@
+// Package database provides the Database interface.
+// All database drivers must implement this interface, register themselves,
+// optionally provide a `WithInstance` function and pass the tests
+// in package database/testing.
 package database
 
 import (
@@ -8,7 +12,7 @@ import (
 )
 
 var (
-	ErrLocked = fmt.Errorf("unable to acquire lock")
+	ErrLocked = fmt.Errorf("can't acquire lock")
 )
 
 const NilVersion int = -1
@@ -16,27 +20,47 @@ const NilVersion int = -1
 var driversMu sync.RWMutex
 var drivers = make(map[string]Driver)
 
+// Driver is an interface every driver must implement.
+// The driver implementation must pass the `Test` in database/testing.
+// Optionally provide a `WithInstance` function, so users can bypass `Open`
+// and use an existing database instance.
+//
+// Implementations must not assume things nor try to correct user input.
+// If in doubt, return an error.
 type Driver interface {
+	// Open returns a new driver instance configured with parameters
+	// coming from the URL string. Migrate will call this function
+	// only once per instance.
 	Open(url string) (Driver, error)
 
+	// Close closes the underlying database instance managed by the driver.
+	// Migrate will call this function only once per instance.
 	Close() error
 
+	// Lock should acquire a database lock so that only one migration process
+	// can run at a time. Migrate will call this function before Run is called.
+	// If the implementation can't provide this functionality, return nil.
 	Lock() error
 
+	// Unlock should release the lock. Migrate will call this function after
+	// all migrations have been run.
 	Unlock() error
 
-	// when version = NilVersion, "deinitialize"
-	// migration can be nil, in that case, just store version
+	// Run applies a migration to the database. Run the migration and store
+	// the version. migration can be nil. In that case, just store the version.
+	// When version -1 is given, the state should be as if no migration had been run.
 	Run(version int, migration io.Reader) error
 
-	// version  > 0: regular version
-	// version   -1: nil version (const NilVersion)
-	// version < -1: will panic
+	// Version returns the currently active version.
+	// When no migration has been run yet, it must return -1.
+	// If the returned version is < -1 it will panic (in the test).
 	Version() (int, error)
 
+	// Drop deletes everyting in the database.
 	Drop() error
 }
 
+// Open returns a new driver instance.
 func Open(url string) (Driver, error) {
 	u, err := nurl.Parse(url)
 	if err != nil {
@@ -57,6 +81,7 @@ func Open(url string) (Driver, error) {
 	return d.Open(url)
 }
 
+// Register globally registers a driver.
 func Register(name string, driver Driver) {
 	driversMu.Lock()
 	defer driversMu.Unlock()

database/driver_test.go

@@ -0,0 +1,8 @@
+package database
+
+func ExampleDriver() {
+	// see database/stub for an example
+
+	// database/stub/stub.go has the driver implementation
+	// database/stub/stub_test.go runs database/testing/test.go:Test
+}