# HG changeset patch
# User Peter Sanchez <peter@netlandish.com>
# Date 1645032495 21600
#      Wed Feb 16 11:28:15 2022 -0600
# Node ID 5e9b5652f8024c6e15de163118f1b8335cfc28db
# Parent  9351697225fe835dcb148bfd5199504cf369dd90
Cleaning up docs a bit

diff --git a/doc.go b/doc.go
--- a/doc.go
+++ b/doc.go
@@ -1,6 +1,6 @@
 // Package migrate is a simple and flexible module to manage database migrations.
 //
 // You can use migration files, queries, and custom functions to manage your
-// migrations. Also has full Context support (globally and per migration) and
+// migrations. Also has full Context support (globally and per migration) with
 // has no external dependencies.
 package migrate
diff --git a/migrate.go b/migrate.go
--- a/migrate.go
+++ b/migrate.go
@@ -26,6 +26,7 @@
 }
 
 // NewEngine returns a new MigrationEngine object
+// bindType should be one of the constants: QUESTION, DOLLAR, NAMED or AT
 func NewEngine(db *sql.DB, migrations []Migration, bindType int, verbose bool) *MigrationEngine {
 	ids := make(idMap)
 	for _, m := range migrations {
@@ -49,6 +50,10 @@
 }
 
 // Migrate will run the migrations using the provided db connection.
+// `stopID` is the migration ID to stop at (after running it)
+// `fakeIt` is a flag that says whether or not to "fake" the migration.
+// Faking the migration means it will add the migration entry into the
+// `migrations` db table as if it ran but without actually running it.
 func (s *MigrationEngine) Migrate(ctx context.Context, stopID string, fakeIt bool) error {
 	s.printf("Creating/checking migrations table...\n")
 	var err error
@@ -106,6 +111,7 @@
 }
 
 // Rollback will run all rollbacks using the provided db connection.
+// `stopID` is the migration ID to stop at (after running it)
 func (s *MigrationEngine) Rollback(ctx context.Context, stopID string) error {
 	s.printf("Creating/checking migrations table...\n")
 	var err error
@@ -175,7 +181,7 @@
 
 func (s *MigrationEngine) getRecord(ctx context.Context, id string) (string, error) {
 	var found string
-	err := WithTx(ctx, TxOptionsRO, func(tx *sql.Tx) error {
+	err := WithTx(ctx, txOptionsRO, func(tx *sql.Tx) error {
 		query := s.rebind("SELECT id FROM migrations WHERE id=?")
 		return tx.QueryRowContext(ctx, query, id).Scan(&found)
 	})
@@ -260,15 +266,17 @@
 	ID string
 	// Optional timeout for this particular migration.
 	Timeout int
-	// Function to migrate forward
+	// Function to migrate forward. Functions should respect context's Done
+	// channel if they want the timeout to work.
 	Migrate func(ctx context.Context, tx *sql.Tx) error
-	// Function to migrate backward
+	// Function to migrate backward. Functions should respect context's Done
+	// channel if they want the timeout to work.
 	Rollback func(ctx context.Context, tx *sql.Tx) error
 }
 
-// QueryMigration will create a Migration using the provided id and
-// query string. It is a helper function designed to simplify the process of
-// creating migrations that only depending on a SQL query string.
+// QueryMigration will create a Migration using the provided migration ID and
+// up/down queries, and migration timeout. If timeout is set, the queries
+// will be cancelled if the timeout period passes.
 func QueryMigration(id, upQuery, downQuery string, timeout int) Migration {
 	queryFn := func(query string) func(ctx context.Context, tx *sql.Tx) error {
 		if query == "" {
@@ -289,7 +297,9 @@
 	return m
 }
 
-// FileMigration will create a Migration using the provided file.
+// FileMigration will create a Migration using the provided migration ID,
+// up/down files, and migration timeout. If timeout is set, the queries
+// will be cancelled if the timeout period passes.
 func FileMigration(id, upFile, downFile string, timeout int) Migration {
 	fileFn := func(filename string) func(ctx context.Context, tx *sql.Tx) error {
 		if filename == "" {
diff --git a/sql.go b/sql.go
--- a/sql.go
+++ b/sql.go
@@ -12,9 +12,13 @@
 // Pulled from sqlx: https://github.com/jmoiron/sqlx
 const (
 	UNKNOWN = iota
+	// Use ? for sql placeholder
 	QUESTION
+	// Use $<num> for sql placeholder
 	DOLLAR
+	// Use :<name> for sql placeholder
 	NAMED
+	// Use @ for sql placeholder
 	AT
 )
 
@@ -58,8 +62,7 @@
 	name string
 }
 
-// TxOptionsRO read only transaction rules
-var TxOptionsRO *sql.TxOptions = &sql.TxOptions{Isolation: 0, ReadOnly: true}
+var txOptionsRO *sql.TxOptions = &sql.TxOptions{Isolation: 0, ReadOnly: true}
 
 // ContextAddTimeout returns a context with query timeout
 func ContextAddTimeout(ctx context.Context, timeout int) (context.Context, context.CancelFunc) {