add missing docstrings

adapter/mongo/result.go

@@ -580,9 +580,9 @@ func queryLog(status *sqladapter.QueryStatus) {
 	}
 
 	if status.Err != nil || slowQuery {
-		db.Log().Warn(status)
+		db.LC().Warn(status)
 		return
 	}
 
-	db.Log().Debug(status)
+	db.LC().Debug(status)
 }

clauses.go

@@ -468,10 +468,22 @@ type ResultMapper interface {
 	One(dest interface{}) error
 }
 
+// BatchInserter provides an interface to do massive insertions in batches.
 type BatchInserter interface {
+	// Values pushes column values to be inserted as part of the batch.
 	Values(...interface{}) BatchInserter
-	NextResult(interface{}) bool
+
+	// NextResult dumps the next slice of results to dst, which can mean having
+	// the IDs of all inserted elements in the batch.
+	NextResult(dst interface{}) bool
+
+	// Done signals that no more elements are going to be added.
 	Done()
+
+	// Wait blocks until the whole batch is executed.
 	Wait() error
+
+	// Err returns the last error that happened while executing the batch (or nil
+	// if no error happened).
 	Err() error
 }

internal/sqladapter/session.go

@@ -641,11 +641,11 @@ func queryLog(status *QueryStatus) {
 	}
 
 	if status.Err != nil || slowQuery {
-		db.Log().Warn(status)
+		db.LC().Warn(status)
 		return
 	}
 
-	db.Log().Debug(status)
+	db.LC().Debug(status)
 }
 
 func (sess *session) StatementPrepare(ctx context.Context, stmt *exql.Statement) (sqlStmt *sql.Stmt, err error) {

internal/testsuite/sql_suite.go

@@ -188,14 +188,14 @@ func (s *SQLTestSuite) TestTruncateAllCollections() {
 }
 
 func (s *SQLTestSuite) TestQueryLogger() {
-	logLevel := db.Log().Level()
+	logLevel := db.LC().Level()
 
-	db.Log().SetLogger(logrus.New())
-	db.Log().SetLevel(db.LogLevelDebug)
+	db.LC().SetLogger(logrus.New())
+	db.LC().SetLevel(db.LogLevelDebug)
 
 	defer func() {
-		db.Log().SetLogger(nil)
-		db.Log().SetLevel(logLevel)
+		db.LC().SetLogger(nil)
+		db.LC().SetLevel(logLevel)
 	}()
 
 	sess := s.Session()

logger.go

@@ -29,8 +29,10 @@ import (
 	"strings"
 )
 
+// LogLevel represents a verbosity level for logs
 type LogLevel int8
 
+// Log levels
 const (
 	LogLevelTrace LogLevel = -1
 
@@ -62,7 +64,8 @@ const (
 
 var defaultLogger Logger = log.New(os.Stdout, "", log.LstdFlags)
 
-// Logger
+// Logger represents a logging interface that is compatible with the standard
+// "log" and with many other logging libraries.
 type Logger interface {
 	Fatal(v ...interface{})
 	Fatalf(format string, v ...interface{})
@@ -74,7 +77,8 @@ type Logger interface {
 	Panicf(format string, v ...interface{})
 }
 
-// LoggingCollector represents a logging collector.
+// LoggingCollector provides different methods for collecting and classifying
+// log messages.
 type LoggingCollector interface {
 	Enabled(LogLevel) bool
 
@@ -224,15 +228,16 @@ var defaultLoggingCollector LoggingCollector = &loggingCollector{
 	logger: defaultLogger,
 }
 
-func Log() LoggingCollector {
+// LC returns the logging collector.
+func LC() LoggingCollector {
 	return defaultLoggingCollector
 }
 
 func init() {
 	if logLevel := strings.ToUpper(os.Getenv("UPPER_DB_LOG")); logLevel != "" {
 		for ll := range logLevels {
 			if ll.String() == logLevel {
-				Log().SetLevel(ll)
+				LC().SetLevel(ll)
 				break
 			}
 		}

logger_test.go

@@ -28,5 +28,5 @@ import (
 
 func TestLogger(t *testing.T) {
 	err := errors.New("fake error")
-	Log().Error(err)
+	LC().Error(err)
 }

record.go

@@ -25,55 +25,58 @@ type Record interface {
 	Store(sess Session) Store
 }
 
+// HasConstraints is an interface for records that defines a Constraints method
+// that returns the record's own constraints.
 type HasConstraints interface {
 	Constraints() Cond
 }
 
-// Validator is an interface that defined an (optional) Validate function for
-// records that is called before persisting a record (creating or updating). If
-// Validate returns an error the current operation is rolled back.
+// Validator is an interface for records that defines an (optional) Validate
+// method that is called before persisting a record (creating or updating).  If
+// Validate returns an error the current operation is cancelled and rolled
+// back.
 type Validator interface {
 	Validate() error
 }
 
-// BeforeCreateHook is an interface that defines an BeforeCreate function for
-// records that is called before creating a record. If BeforeCreate returns an
-// error the create process is rolled back.
+// BeforeCreateHook is an interface for records that defines an BeforeCreate
+// method that is called before creating a record. If BeforeCreate returns an
+// error the create process is cancelled and rolled back.
 type BeforeCreateHook interface {
 	BeforeCreate(Session) error
 }
 
-// AfterCreateHook is an interface that defines an AfterCreate function for
-// records that is called after creating a record. If AfterCreate returns an
-// error the create process is rolled back.
+// AfterCreateHook is an interface for records that defines an AfterCreate
+// method that is called after creating a record. If AfterCreate returns an
+// error the create process is cancelled and rolled back.
 type AfterCreateHook interface {
 	AfterCreate(Session) error
 }
 
-// BeforeUpdateHook is an interface that defines a BeforeUpdate function for
-// records that is called before updating a record. If BeforeUpdate returns an
-// error the update process is rolled back.
+// BeforeUpdateHook is an interface for records that defines a BeforeUpdate
+// method that is called before updating a record. If BeforeUpdate returns an
+// error the update process is cancelled and rolled back.
 type BeforeUpdateHook interface {
 	BeforeUpdate(Session) error
 }
 
-// AfterUpdateHook is an interface that defines an AfterUpdate function for
-// records that is called after updating a record. If AfterUpdate returns an
-// error the update process is rolled back.
+// AfterUpdateHook is an interface for records that defines an AfterUpdate
+// method that is called after updating a record. If AfterUpdate returns an
+// error the update process is cancelled and rolled back.
 type AfterUpdateHook interface {
 	AfterUpdate(Session) error
 }
 
-// BeforeDeleteHook is an interface that defines a BeforeDelete function for
-// records that is called before removing a record. If BeforeDelete returns an
-// error the delete process is rolled back.
+// BeforeDeleteHook is an interface for records that defines a BeforeDelete
+// method that is called before removing a record. If BeforeDelete returns an
+// error the delete process is cancelled and rolled back.
 type BeforeDeleteHook interface {
 	BeforeDelete(Session) error
 }
 
-// AfterDeleteHook is an interface that defines a AfterDelete function for
-// records that is called after removing a record. If AfterDelete returns
-// an error the delete process is rolled back.
+// AfterDeleteHook is an interface for records that defines a AfterDelete
+// method that is called after removing a record. If AfterDelete returns an
+// error the delete process is cancelled and rolled back.
 type AfterDeleteHook interface {
 	AfterDelete(Session) error
 }

result.go

@@ -179,20 +179,25 @@ type Result interface {
 	Close() error
 }
 
+// InsertResult provides infomation about an insert operation.
 type InsertResult struct {
 	id interface{}
 }
 
+// ID returns the ID of the newly inserted record.
 func (r *InsertResult) ID() ID {
 	return r.id
 }
 
+// Value satisfies driver.Valuer
 func (r InsertResult) Value() (driver.Value, error) {
 	return r.id, nil
 }
 
+// NewInsertResult creates an InsertResult
 func NewInsertResult(id interface{}) *InsertResult {
 	return &InsertResult{id: id}
 }
 
+// ID represents a record ID
 type ID interface{}

store.go

@@ -21,26 +21,37 @@
 
 package db
 
+// Store represents a data store.
 type Store interface {
 	Collection
 }
 
+// StoreSaver is an interface for data stores that defines a Save method that
+// has the task of persisting a record.
 type StoreSaver interface {
 	Save(record Record) error
 }
 
+// StoreCreator is an interface for data stores that defines a Create method
+// that has the task of creating a new record.
 type StoreCreator interface {
 	Create(record Record) error
 }
 
+// StoreDeleter is an interface for data stores that defines a Delete method
+// that has the task of removing a record.
 type StoreDeleter interface {
 	Delete(record Record) error
 }
 
+// StoreUpdater is an interface for data stores that defines a Update method
+// that has the task of updating a record.
 type StoreUpdater interface {
 	Update(record Record) error
 }
 
+// StoreGetter is an interface for data stores that defines a Get method that
+// has the task of retrieving a record.
 type StoreGetter interface {
 	Get(record Record, id interface{}) error
 }