From bd9535d781a781aaa49019a489ac3e568ec9c77a Mon Sep 17 00:00:00 2001
From: Lunny Xiao <xiaolunwen@gmail.com>
Date: Mon, 12 Apr 2021 09:19:08 +0800
Subject: [PATCH] Fix comments (#1893)

Reviewed-on: https://gitea.com/xorm/xorm/pulls/1893
Co-authored-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-committed-by: Lunny Xiao <xiaolunwen@gmail.com>
---
 .revive.toml                      |  4 +++-
 caches/encode.go                  |  9 ++++++++-
 core/tx.go                        | 25 +++++++++++++++++++++++++
 dialects/driver.go                |  8 ++++++--
 dialects/filter.go                |  1 +
 dialects/time.go                  |  1 +
 integrations/tests.go             |  5 +----
 internal/statements/expr_param.go |  1 +
 internal/statements/statement.go  | 22 ++++++++++++++++++----
 schemas/type.go                   | 12 ++++++++++++
 10 files changed, 76 insertions(+), 12 deletions(-)

diff --git a/.revive.toml b/.revive.toml
index 64e223bb..6dec7465 100644
--- a/.revive.toml
+++ b/.revive.toml
@@ -15,6 +15,7 @@ warningCode = 1
 [rule.if-return]
 [rule.increment-decrement]
 [rule.var-naming]
+  arguments = [["ID", "UID", "UUID", "URL", "JSON"], []]
 [rule.var-declaration]
 [rule.package-comments]
 [rule.range]
@@ -22,4 +23,5 @@ warningCode = 1
 [rule.time-naming]
 [rule.unexported-return]
 [rule.indent-error-flow]
-[rule.errorf]
\ No newline at end of file
+[rule.errorf]
+[rule.struct-tag]
\ No newline at end of file
diff --git a/caches/encode.go b/caches/encode.go
index 4ba39924..95536d7e 100644
--- a/caches/encode.go
+++ b/caches/encode.go
@@ -13,22 +13,26 @@ import (
 	"io"
 )
 
-// md5 hash string
+// Md5 return md5 hash string
 func Md5(str string) string {
 	m := md5.New()
 	io.WriteString(m, str)
 	return fmt.Sprintf("%x", m.Sum(nil))
 }
+
+// Encode Encode data
 func Encode(data interface{}) ([]byte, error) {
 	//return JsonEncode(data)
 	return GobEncode(data)
 }
 
+// Decode decode data
 func Decode(data []byte, to interface{}) error {
 	//return JsonDecode(data, to)
 	return GobDecode(data, to)
 }
 
+// GobEncode encode data with gob
 func GobEncode(data interface{}) ([]byte, error) {
 	var buf bytes.Buffer
 	enc := gob.NewEncoder(&buf)
@@ -39,12 +43,14 @@ func GobEncode(data interface{}) ([]byte, error) {
 	return buf.Bytes(), nil
 }
 
+// GobDecode decode data with gob
 func GobDecode(data []byte, to interface{}) error {
 	buf := bytes.NewBuffer(data)
 	dec := gob.NewDecoder(buf)
 	return dec.Decode(to)
 }
 
+// JsonEncode encode data with json
 func JsonEncode(data interface{}) ([]byte, error) {
 	val, err := json.Marshal(data)
 	if err != nil {
@@ -53,6 +59,7 @@ func JsonEncode(data interface{}) ([]byte, error) {
 	return val, nil
 }
 
+// JsonDecode decode data with json
 func JsonDecode(data []byte, to interface{}) error {
 	return json.Unmarshal(data, to)
 }
diff --git a/core/tx.go b/core/tx.go
index a85a6874..24d548b3 100644
--- a/core/tx.go
+++ b/core/tx.go
@@ -22,6 +22,7 @@ type Tx struct {
 	ctx context.Context
 }
 
+// BeginTx begin a transaction with option
 func (db *DB) BeginTx(ctx context.Context, opts *sql.TxOptions) (*Tx, error) {
 	hookCtx := contexts.NewContextHook(ctx, "BEGIN TRANSACTION", nil)
 	ctx, err := db.beforeProcess(hookCtx)
@@ -36,10 +37,12 @@ func (db *DB) BeginTx(ctx context.Context, opts *sql.TxOptions) (*Tx, error) {
 	return &Tx{tx, db, ctx}, nil
 }
 
+// Begin begins a transaction
 func (db *DB) Begin() (*Tx, error) {
 	return db.BeginTx(context.Background(), nil)
 }
 
+// Commit submit the transaction
 func (tx *Tx) Commit() error {
 	hookCtx := contexts.NewContextHook(tx.ctx, "COMMIT", nil)
 	ctx, err := tx.db.beforeProcess(hookCtx)
@@ -54,6 +57,7 @@ func (tx *Tx) Commit() error {
 	return nil
 }
 
+// Rollback rollback the transaction
 func (tx *Tx) Rollback() error {
 	hookCtx := contexts.NewContextHook(tx.ctx, "ROLLBACK", nil)
 	ctx, err := tx.db.beforeProcess(hookCtx)
@@ -68,6 +72,7 @@ func (tx *Tx) Rollback() error {
 	return nil
 }
 
+// PrepareContext prepare the query
 func (tx *Tx) PrepareContext(ctx context.Context, query string) (*Stmt, error) {
 	names := make(map[string]int)
 	var i int
@@ -89,19 +94,23 @@ func (tx *Tx) PrepareContext(ctx context.Context, query string) (*Stmt, error) {
 	return &Stmt{stmt, tx.db, names, query}, nil
 }
 
+// Prepare prepare the query
 func (tx *Tx) Prepare(query string) (*Stmt, error) {
 	return tx.PrepareContext(context.Background(), query)
 }
 
+// StmtContext creates Stmt with context
 func (tx *Tx) StmtContext(ctx context.Context, stmt *Stmt) *Stmt {
 	stmt.Stmt = tx.Tx.StmtContext(ctx, stmt.Stmt)
 	return stmt
 }
 
+// Stmt creates Stmt
 func (tx *Tx) Stmt(stmt *Stmt) *Stmt {
 	return tx.StmtContext(context.Background(), stmt)
 }
 
+// ExecMapContext executes query with args in a map
 func (tx *Tx) ExecMapContext(ctx context.Context, query string, mp interface{}) (sql.Result, error) {
 	query, args, err := MapToSlice(query, mp)
 	if err != nil {
@@ -110,10 +119,12 @@ func (tx *Tx) ExecMapContext(ctx context.Context, query string, mp interface{})
 	return tx.ExecContext(ctx, query, args...)
 }
 
+// ExecMap executes query with args in a map
 func (tx *Tx) ExecMap(query string, mp interface{}) (sql.Result, error) {
 	return tx.ExecMapContext(context.Background(), query, mp)
 }
 
+// ExecStructContext executes query with args in a struct
 func (tx *Tx) ExecStructContext(ctx context.Context, query string, st interface{}) (sql.Result, error) {
 	query, args, err := StructToSlice(query, st)
 	if err != nil {
@@ -122,6 +133,7 @@ func (tx *Tx) ExecStructContext(ctx context.Context, query string, st interface{
 	return tx.ExecContext(ctx, query, args...)
 }
 
+// ExecContext executes a query with args
 func (tx *Tx) ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error) {
 	hookCtx := contexts.NewContextHook(ctx, query, args)
 	ctx, err := tx.db.beforeProcess(hookCtx)
@@ -136,10 +148,12 @@ func (tx *Tx) ExecContext(ctx context.Context, query string, args ...interface{}
 	return res, err
 }
 
+// ExecStruct executes query with args in a struct
 func (tx *Tx) ExecStruct(query string, st interface{}) (sql.Result, error) {
 	return tx.ExecStructContext(context.Background(), query, st)
 }
 
+// QueryContext query with args
 func (tx *Tx) QueryContext(ctx context.Context, query string, args ...interface{}) (*Rows, error) {
 	hookCtx := contexts.NewContextHook(ctx, query, args)
 	ctx, err := tx.db.beforeProcess(hookCtx)
@@ -157,10 +171,12 @@ func (tx *Tx) QueryContext(ctx context.Context, query string, args ...interface{
 	return &Rows{rows, tx.db}, nil
 }
 
+// Query query with args
 func (tx *Tx) Query(query string, args ...interface{}) (*Rows, error) {
 	return tx.QueryContext(context.Background(), query, args...)
 }
 
+// QueryMapContext query with args in a map
 func (tx *Tx) QueryMapContext(ctx context.Context, query string, mp interface{}) (*Rows, error) {
 	query, args, err := MapToSlice(query, mp)
 	if err != nil {
@@ -169,10 +185,12 @@ func (tx *Tx) QueryMapContext(ctx context.Context, query string, mp interface{})
 	return tx.QueryContext(ctx, query, args...)
 }
 
+// QueryMap query with args in a map
 func (tx *Tx) QueryMap(query string, mp interface{}) (*Rows, error) {
 	return tx.QueryMapContext(context.Background(), query, mp)
 }
 
+// QueryStructContext query with args in struct
 func (tx *Tx) QueryStructContext(ctx context.Context, query string, st interface{}) (*Rows, error) {
 	query, args, err := StructToSlice(query, st)
 	if err != nil {
@@ -181,19 +199,23 @@ func (tx *Tx) QueryStructContext(ctx context.Context, query string, st interface
 	return tx.QueryContext(ctx, query, args...)
 }
 
+// QueryStruct query with args in struct
 func (tx *Tx) QueryStruct(query string, st interface{}) (*Rows, error) {
 	return tx.QueryStructContext(context.Background(), query, st)
 }
 
+// QueryRowContext query one row with args
 func (tx *Tx) QueryRowContext(ctx context.Context, query string, args ...interface{}) *Row {
 	rows, err := tx.QueryContext(ctx, query, args...)
 	return &Row{rows, err}
 }
 
+// QueryRow query one row with args
 func (tx *Tx) QueryRow(query string, args ...interface{}) *Row {
 	return tx.QueryRowContext(context.Background(), query, args...)
 }
 
+// QueryRowMapContext query one row with args in a map
 func (tx *Tx) QueryRowMapContext(ctx context.Context, query string, mp interface{}) *Row {
 	query, args, err := MapToSlice(query, mp)
 	if err != nil {
@@ -202,10 +224,12 @@ func (tx *Tx) QueryRowMapContext(ctx context.Context, query string, mp interface
 	return tx.QueryRowContext(ctx, query, args...)
 }
 
+// QueryRowMap query one row with args in a map
 func (tx *Tx) QueryRowMap(query string, mp interface{}) *Row {
 	return tx.QueryRowMapContext(context.Background(), query, mp)
 }
 
+// QueryRowStructContext query one row with args in struct
 func (tx *Tx) QueryRowStructContext(ctx context.Context, query string, st interface{}) *Row {
 	query, args, err := StructToSlice(query, st)
 	if err != nil {
@@ -214,6 +238,7 @@ func (tx *Tx) QueryRowStructContext(ctx context.Context, query string, st interf
 	return tx.QueryRowContext(ctx, query, args...)
 }
 
+// QueryRowStruct query one row with args in struct
 func (tx *Tx) QueryRowStruct(query string, st interface{}) *Row {
 	return tx.QueryRowStructContext(context.Background(), query, st)
 }
diff --git a/dialects/driver.go b/dialects/driver.go
index ae3afe42..bb46a936 100644
--- a/dialects/driver.go
+++ b/dialects/driver.go
@@ -8,6 +8,7 @@ import (
 	"fmt"
 )
 
+// Driver represents a database driver
 type Driver interface {
 	Parse(string, string) (*URI, error)
 }
@@ -16,6 +17,7 @@ var (
 	drivers = map[string]Driver{}
 )
 
+// RegisterDriver register a driver
 func RegisterDriver(driverName string, driver Driver) {
 	if driver == nil {
 		panic("core: Register driver is nil")
@@ -26,10 +28,12 @@ func RegisterDriver(driverName string, driver Driver) {
 	drivers[driverName] = driver
 }
 
+// QueryDriver query a driver with name
 func QueryDriver(driverName string) Driver {
 	return drivers[driverName]
 }
 
+// RegisteredDriverSize returned all drivers's length
 func RegisteredDriverSize() int {
 	return len(drivers)
 }
@@ -38,7 +42,7 @@ func RegisteredDriverSize() int {
 func OpenDialect(driverName, connstr string) (Dialect, error) {
 	driver := QueryDriver(driverName)
 	if driver == nil {
-		return nil, fmt.Errorf("Unsupported driver name: %v", driverName)
+		return nil, fmt.Errorf("unsupported driver name: %v", driverName)
 	}
 
 	uri, err := driver.Parse(driverName, connstr)
@@ -48,7 +52,7 @@ func OpenDialect(driverName, connstr string) (Dialect, error) {
 
 	dialect := QueryDialect(uri.DBType)
 	if dialect == nil {
-		return nil, fmt.Errorf("Unsupported dialect type: %v", uri.DBType)
+		return nil, fmt.Errorf("unsupported dialect type: %v", uri.DBType)
 	}
 
 	dialect.Init(uri)
diff --git a/dialects/filter.go b/dialects/filter.go
index 6968b6ce..2a36a731 100644
--- a/dialects/filter.go
+++ b/dialects/filter.go
@@ -38,6 +38,7 @@ func convertQuestionMark(sql, prefix string, start int) string {
 	return buf.String()
 }
 
+// Do implements Filter
 func (s *SeqFilter) Do(sql string) string {
 	return convertQuestionMark(sql, s.Prefix, s.Start)
 }
diff --git a/dialects/time.go b/dialects/time.go
index 9a3c82a4..5aee0c10 100644
--- a/dialects/time.go
+++ b/dialects/time.go
@@ -38,6 +38,7 @@ func FormatTime(dialect Dialect, sqlTypeName string, t time.Time) (v interface{}
 	return
 }
 
+// FormatColumnTime format column time
 func FormatColumnTime(dialect Dialect, defaultTimeZone *time.Location, col *schemas.Column, t time.Time) (v interface{}) {
 	if t.IsZero() {
 		if col.Nullable {
diff --git a/integrations/tests.go b/integrations/tests.go
index 512f3962..8b14b0f4 100644
--- a/integrations/tests.go
+++ b/integrations/tests.go
@@ -166,10 +166,7 @@ func createEngine(dbType, connStr string) error {
 	for _, table := range tables {
 		tableNames = append(tableNames, table.Name)
 	}
-	if err = testEngine.DropTables(tableNames...); err != nil {
-		return err
-	}
-	return nil
+	return testEngine.DropTables(tableNames...)
 }
 
 // PrepareEngine prepare tests ORM engine
diff --git a/internal/statements/expr_param.go b/internal/statements/expr_param.go
index 6657408e..d0c355d3 100644
--- a/internal/statements/expr_param.go
+++ b/internal/statements/expr_param.go
@@ -12,6 +12,7 @@ import (
 	"xorm.io/xorm/schemas"
 )
 
+// ErrUnsupportedExprType represents an error with unsupported express type
 type ErrUnsupportedExprType struct {
 	tp string
 }
diff --git a/internal/statements/statement.go b/internal/statements/statement.go
index a4294bec..87f785ae 100644
--- a/internal/statements/statement.go
+++ b/internal/statements/statement.go
@@ -103,6 +103,7 @@ func (statement *Statement) GenRawSQL() string {
 	return statement.ReplaceQuote(statement.RawSQL)
 }
 
+// GenCondSQL generates condition SQL
 func (statement *Statement) GenCondSQL(condOrBuilder interface{}) (string, []interface{}, error) {
 	condSQL, condArgs, err := builder.ToSQL(condOrBuilder)
 	if err != nil {
@@ -119,11 +120,12 @@ func (statement *Statement) ReplaceQuote(sql string) string {
 	return statement.dialect.Quoter().Replace(sql)
 }
 
+// SetContextCache sets context cache
 func (statement *Statement) SetContextCache(ctxCache contexts.ContextCache) {
 	statement.Context = ctxCache
 }
 
-// Init reset all the statement's fields
+// Reset reset all the statement's fields
 func (statement *Statement) Reset() {
 	statement.RefTable = nil
 	statement.Start = 0
@@ -163,7 +165,7 @@ func (statement *Statement) Reset() {
 	statement.LastError = nil
 }
 
-// NoAutoCondition if you do not want convert bean's field as query condition, then use this function
+// SetNoAutoCondition if you do not want convert bean's field as query condition, then use this function
 func (statement *Statement) SetNoAutoCondition(no ...bool) *Statement {
 	statement.NoAutoCondition = true
 	if len(no) > 0 {
@@ -271,6 +273,7 @@ func (statement *Statement) NotIn(column string, args ...interface{}) *Statement
 	return statement
 }
 
+// SetRefValue set ref value
 func (statement *Statement) SetRefValue(v reflect.Value) error {
 	var err error
 	statement.RefTable, err = statement.tagParser.ParseWithCache(reflect.Indirect(v))
@@ -285,6 +288,7 @@ func rValue(bean interface{}) reflect.Value {
 	return reflect.Indirect(reflect.ValueOf(bean))
 }
 
+// SetRefBean set ref bean
 func (statement *Statement) SetRefBean(bean interface{}) error {
 	var err error
 	statement.RefTable, err = statement.tagParser.ParseWithCache(rValue(bean))
@@ -390,6 +394,7 @@ func (statement *Statement) Cols(columns ...string) *Statement {
 	return statement
 }
 
+// ColumnStr returns column string
 func (statement *Statement) ColumnStr() string {
 	return statement.dialect.Quoter().Join(statement.ColumnMap, ", ")
 }
@@ -493,11 +498,12 @@ func (statement *Statement) Asc(colNames ...string) *Statement {
 	return statement
 }
 
+// Conds returns condtions
 func (statement *Statement) Conds() builder.Cond {
 	return statement.cond
 }
 
-// Table tempororily set table name, the parameter could be a string or a pointer of struct
+// SetTable tempororily set table name, the parameter could be a string or a pointer of struct
 func (statement *Statement) SetTable(tableNameOrBean interface{}) error {
 	v := rValue(tableNameOrBean)
 	t := v.Type()
@@ -564,7 +570,7 @@ func (statement *Statement) Join(joinOP string, tablename interface{}, condition
 	return statement
 }
 
-// tbName get some table's table name
+// tbNameNoSchema get some table's table name
 func (statement *Statement) tbNameNoSchema(table *schemas.Table) string {
 	if len(statement.AltTableName) > 0 {
 		return statement.AltTableName
@@ -591,6 +597,7 @@ func (statement *Statement) SetUnscoped() *Statement {
 	return statement
 }
 
+// GetUnscoped return true if it's unscoped
 func (statement *Statement) GetUnscoped() bool {
 	return statement.unscoped
 }
@@ -636,6 +643,7 @@ func (statement *Statement) genColumnStr() string {
 	return buf.String()
 }
 
+// GenCreateTableSQL generated create table SQL
 func (statement *Statement) GenCreateTableSQL() []string {
 	statement.RefTable.StoreEngine = statement.StoreEngine
 	statement.RefTable.Charset = statement.Charset
@@ -643,6 +651,7 @@ func (statement *Statement) GenCreateTableSQL() []string {
 	return s
 }
 
+// GenIndexSQL generated create index SQL
 func (statement *Statement) GenIndexSQL() []string {
 	var sqls []string
 	tbName := statement.TableName()
@@ -659,6 +668,7 @@ func uniqueName(tableName, uqeName string) string {
 	return fmt.Sprintf("UQE_%v_%v", tableName, uqeName)
 }
 
+// GenUniqueSQL generates unique SQL
 func (statement *Statement) GenUniqueSQL() []string {
 	var sqls []string
 	tbName := statement.TableName()
@@ -671,6 +681,7 @@ func (statement *Statement) GenUniqueSQL() []string {
 	return sqls
 }
 
+// GenDelIndexSQL generate delete index SQL
 func (statement *Statement) GenDelIndexSQL() []string {
 	var sqls []string
 	tbName := statement.TableName()
@@ -896,6 +907,7 @@ func (statement *Statement) buildConds2(table *schemas.Table, bean interface{},
 	return builder.And(conds...), nil
 }
 
+// BuildConds builds condition
 func (statement *Statement) BuildConds(table *schemas.Table, bean interface{}, includeVersion bool, includeUpdated bool, includeNil bool, includeAutoIncr bool, addedTableName bool) (builder.Cond, error) {
 	return statement.buildConds2(table, bean, includeVersion, includeUpdated, includeNil, includeAutoIncr, statement.allUseBool, statement.useAllCols,
 		statement.unscoped, statement.MustColumnMap, statement.TableName(), statement.TableAlias, addedTableName)
@@ -917,6 +929,7 @@ func (statement *Statement) mergeConds(bean interface{}) error {
 	return nil
 }
 
+// GenConds generates conditions
 func (statement *Statement) GenConds(bean interface{}) (string, []interface{}, error) {
 	if err := statement.mergeConds(bean); err != nil {
 		return "", nil, err
@@ -930,6 +943,7 @@ func (statement *Statement) quoteColumnStr(columnStr string) string {
 	return statement.dialect.Quoter().Join(columns, ",")
 }
 
+// ConvertSQLOrArgs converts sql or args
 func (statement *Statement) ConvertSQLOrArgs(sqlOrArgs ...interface{}) (string, []interface{}, error) {
 	sql, args, err := convertSQLOrArgs(sqlOrArgs...)
 	if err != nil {
diff --git a/schemas/type.go b/schemas/type.go
index 6b50d184..c6cdfb87 100644
--- a/schemas/type.go
+++ b/schemas/type.go
@@ -11,8 +11,10 @@ import (
 	"time"
 )
 
+// DBType represents a database type
 type DBType string
 
+// enumerates all database types
 const (
 	POSTGRES DBType = "postgres"
 	SQLITE   DBType = "sqlite3"
@@ -28,6 +30,7 @@ type SQLType struct {
 	DefaultLength2 int
 }
 
+// enumerates all columns types
 const (
 	UNKNOW_TYPE = iota
 	TEXT_TYPE
@@ -37,6 +40,7 @@ const (
 	ARRAY_TYPE
 )
 
+// IsType reutrns ture if the column type is the same as the parameter
 func (s *SQLType) IsType(st int) bool {
 	if t, ok := SqlTypes[s.Name]; ok && t == st {
 		return true
@@ -44,34 +48,42 @@ func (s *SQLType) IsType(st int) bool {
 	return false
 }
 
+// IsText returns true if column is a text type
 func (s *SQLType) IsText() bool {
 	return s.IsType(TEXT_TYPE)
 }
 
+// IsBlob returns true if column is a binary type
 func (s *SQLType) IsBlob() bool {
 	return s.IsType(BLOB_TYPE)
 }
 
+// IsTime returns true if column is a time type
 func (s *SQLType) IsTime() bool {
 	return s.IsType(TIME_TYPE)
 }
 
+// IsNumeric returns true if column is a numeric type
 func (s *SQLType) IsNumeric() bool {
 	return s.IsType(NUMERIC_TYPE)
 }
 
+// IsArray returns true if column is an array type
 func (s *SQLType) IsArray() bool {
 	return s.IsType(ARRAY_TYPE)
 }
 
+// IsJson returns true if column is an array type
 func (s *SQLType) IsJson() bool {
 	return s.Name == Json || s.Name == Jsonb
 }
 
+// IsXML returns true if column is an xml type
 func (s *SQLType) IsXML() bool {
 	return s.Name == XML
 }
 
+// enumerates all the database column types
 var (
 	Bit            = "BIT"
 	UnsignedBit    = "UNSIGNED BIT"