@@ 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

          

@@ 26,6 26,7 @@ type MigrationEngine struct {
 }
 
 // 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 @@ func NewEngine(db *sql.DB, migrations []
 }
 
 // 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 @@ func (s *MigrationEngine) Migrate(ctx co
 }
 
 // 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) rebind(query s
 
 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 @@ type Migration struct {
 	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 @@ func QueryMigration(id, upQuery, downQue
 	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 == "" {

          

@@ 12,9 12,13 @@ import (
 // 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 @@ type contextKey struct {
 	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) {