From 9994306945643597b79850d148da7bf405e4d9b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Justin=20M=C3=BCller?= Date: Mon, 2 Dec 2019 10:29:53 +0100 Subject: [PATCH] Correct and complete code docs refs #52 --- configobject/history/history.go | 4 ++-- configobject/statesync/statesync.go | 14 +++++++------- connection/mysql.go | 24 ++++++++++++------------ connection/mysql_utils.go | 12 ++++++------ connection/redis.go | 14 +++++++------- ha/heartbeat.go | 2 +- utils/benchmark.go | 2 +- utils/convert.go | 14 +++++++------- 8 files changed, 43 insertions(+), 43 deletions(-) diff --git a/configobject/history/history.go b/configobject/history/history.go index 85bfcb9c..c129e576 100644 --- a/configobject/history/history.go +++ b/configobject/history/history.go @@ -31,7 +31,7 @@ var mysqlObservers = func() (mysqlObservers map[string]prometheus.Observer) { var historyCounter = make(map[string]int) var historyCounterLock = sync.Mutex{} -//Logs the amount of history entries added every 20 seconds +// logHistoryCounters logs the amount of history entries added every 20 seconds. func logHistoryCounters() { every20s := time.NewTicker(time.Second * 20) defer every20s.Stop() @@ -508,7 +508,7 @@ func historyWorker(super *supervisor.Supervisor, historyType string, preparedSta log.Debugf("%d %s history entries broken", brokenEntries, historyType) } -//Removes one redis.XMessage at given index from given slice and returns the resulting slice +// removeEntryFromEntriesSlice removes one redis.XMessage at given index from given slice and returns the resulting slice. func removeEntryFromEntriesSlice(s []redis.XMessage, i int) []redis.XMessage { s[len(s)-1], s[i] = s[i], s[len(s)-1] return s[:len(s)-1] diff --git a/configobject/statesync/statesync.go b/configobject/statesync/statesync.go index 862f1541..b5f8b931 100644 --- a/configobject/statesync/statesync.go +++ b/configobject/statesync/statesync.go @@ -14,7 +14,7 @@ import ( "time" ) -//Counter on how many host/service states have synced since the last logSyncCounters() +// syncCounter counts on how many host/service states have synced since the last logSyncCounters(). var syncCounter = make(map[string]int) var syncCounterLock = sync.Mutex{} @@ -28,7 +28,7 @@ var mysqlObservers = func() (mysqlObservers map[string]prometheus.Observer) { return }() -//Start the sync goroutines for hosts and services +// StartStateSync starts the sync goroutines for hosts and services. func StartStateSync(super *supervisor.Supervisor) { go func() { for { @@ -45,7 +45,7 @@ func StartStateSync(super *supervisor.Supervisor) { go logSyncCounters() } -//Logs the amount of synced states every 20 seconds +// logSyncCounters logs the amount of synced states every 20 seconds. func logSyncCounters() { every20s := time.NewTicker(time.Second * 20) defer every20s.Stop() @@ -61,7 +61,7 @@ func logSyncCounters() { } } -//Tries to sync the states of given object type every second +// syncStates tries to sync the states of given object type every second. func syncStates(super *supervisor.Supervisor, objectType string) { if super.EnvId == nil { log.Debug("StateSync: Waiting for EnvId to be set") @@ -173,13 +173,13 @@ func syncStates(super *supervisor.Supervisor, objectType string) { StateSyncsTotal.WithLabelValues(objectType).Add(float64(len(storedStateIds))) } -//Removes one redis.XMessage at given index from given slice and returns the resulting slice +// removeStateFromStatesSlice removes one redis.XMessage at given index from given slice and returns the resulting slice. func removeStateFromStatesSlice(s []redis.XMessage, i int) []redis.XMessage { s[len(s)-1], s[i] = s[i], s[len(s)-1] return s[:len(s)-1] } -//Converts a Icinga state type(0 for soft, 1 for hard) we got from Redis into a DB state type(soft, hard) +// redisStateTypeToDBStateType converts a Icinga state type(0 for soft, 1 for hard) we got from Redis into a DB state type(soft, hard). func redisStateTypeToDBStateType(value interface{}) string { if value == "1" { return "hard" @@ -188,7 +188,7 @@ func redisStateTypeToDBStateType(value interface{}) string { } } -//Converts a int we got from Redis into a DB int +// redisIntToDBInt converts a int we got from Redis into a DB int. func redisIntToDBInt(value interface{}) string { if value == nil || value == "" { return "0" diff --git a/connection/mysql.go b/connection/mysql.go index 53d26ddb..d6dff343 100644 --- a/connection/mysql.go +++ b/connection/mysql.go @@ -59,7 +59,7 @@ var connectionErrors = []string{ "operation timed out", } -// This is used in SqlFetchAll and SqlFetchAllQuiet +// DbClientOrTransaction is used in SqlFetchAll and SqlFetchAllQuiet. type DbClientOrTransaction interface { Query(query string, args ...interface{}) (*sql.Rows, error) Exec(query string, args ...interface{}) (sql.Result, error) @@ -106,7 +106,7 @@ func NewDBWrapper(dbDsn string, maxOpenConns int) (*DBWrapper, error) { return &dbw, nil } -// Database wrapper including helper functions +// DBWrapper is a database wrapper including helper functions. type DBWrapper struct { Db DbClient ConnectedAtomic *uint32 //uint32 to be able to use atomic operations @@ -231,7 +231,7 @@ func (dbw *DBWrapper) SqlQuery(query string, args ...interface{}) (*sql.Rows, er } } -// Wrapper around Db.BeginTx() for auto-logging +// SqlBegin is a wrapper around Db.BeginTx() for auto-logging. func (dbw *DBWrapper) SqlBegin(concurrencySafety bool, quiet bool) (DbTransaction, error) { DbOperationsBegin.Inc() var isoLvl sql.IsolationLevel @@ -274,7 +274,7 @@ func (dbw *DBWrapper) SqlBegin(concurrencySafety bool, quiet bool) (DbTransactio } } -// Wrapper around tx.Commit() for auto-logging +// SqlCommit is a wrapper around tx.Commit() for auto-logging. func (dbw *DBWrapper) SqlCommit(tx DbTransaction, quiet bool) error { DbOperationsCommit.Inc() for { @@ -309,7 +309,7 @@ func (dbw *DBWrapper) SqlCommit(tx DbTransaction, quiet bool) error { } } -// Wrapper around tx.Rollback() for auto-logging +// SqlRollback is a wrapper around tx.Rollback() for auto-logging. func (dbw *DBWrapper) SqlRollback(tx DbTransaction, quiet bool) error { DbOperationsRollback.Inc() for { @@ -344,22 +344,22 @@ func (dbw *DBWrapper) SqlRollback(tx DbTransaction, quiet bool) error { } } -// Wrapper around sql.Exec() for auto-logging +// SqlExec is a wrapper around sql.Exec() for auto-logging. func (dbw *DBWrapper) SqlExec(opObserver prometheus.Observer, sql string, args ...interface{}) (sql.Result, error) { return dbw.sqlExecInternal(dbw.Db, opObserver, sql, false, args...) } -// No logging, no benchmarking +// SqlExecQuiet is like SqlExec, but doesn't log or benchmark. func (dbw *DBWrapper) SqlExecQuiet(opObserver prometheus.Observer, sql string, args ...interface{}) (sql.Result, error) { return dbw.sqlExecInternal(dbw.Db, opObserver, sql, true, args...) } -// Wrapper around tx.Exec() for auto-logging +// SqlExecTx is a wrapper around tx.Exec() for auto-logging. func (dbw *DBWrapper) SqlExecTx(tx DbTransaction, opObserver prometheus.Observer, sql string, args ...interface{}) (sql.Result, error) { return dbw.sqlExecInternal(tx, opObserver, sql, false, args...) } -// No logging, no benchmarking +// SqlExecTxQuiet is like SqlExecTx, but doesn't log or benchmark. func (dbw *DBWrapper) SqlExecTxQuiet(tx DbTransaction, opObserver prometheus.Observer, sql string, args ...interface{}) (sql.Result, error) { return dbw.sqlExecInternal(tx, opObserver, sql, true, args...) } @@ -380,7 +380,7 @@ func (dbw *DBWrapper) SqlFetchAllTxQuiet(tx DbTransaction, queryObserver prometh return dbw.sqlFetchAllInternal(tx, queryObserver, query, true, args...) } -// Wrapper around sql.Exec() for auto-logging +// sqlExecInternal is a wrapper around sql.Exec() for auto-logging. func (dbw *DBWrapper) sqlExecInternal(db DbClientOrTransaction, opObserver prometheus.Observer, sql string, quiet bool, args ...interface{}) (sql.Result, error) { for { if !dbw.IsConnected() { @@ -421,7 +421,7 @@ func (dbw *DBWrapper) sqlExecInternal(db DbClientOrTransaction, opObserver prome } } -// Wrapper around Db.SqlQuery() for auto-logging +// sqlFetchAllInternal is a wrapper around Db.SqlQuery() for auto-logging. func (dbw *DBWrapper) sqlFetchAllInternal(db DbClientOrTransaction, queryObserver prometheus.Observer, query string, quiet bool, args ...interface{}) ([][]interface{}, error) { for { if !dbw.IsConnected() { @@ -582,7 +582,7 @@ func (dbw DBWrapper) SqlTransaction(concurrencySafety bool, retryOnConnectionFai } } -// Executes the given function inside a transaction +// sqlTryTransaction executes the given function inside a transaction. func (dbw *DBWrapper) sqlTryTransaction(f func(transaction DbTransaction) error, concurrencySafety bool, quiet bool) error { tx, errBegin := dbw.SqlBegin(concurrencySafety, quiet) if errBegin != nil { diff --git a/connection/mysql_utils.go b/connection/mysql_utils.go index 8d34c264..e231ddcf 100644 --- a/connection/mysql_utils.go +++ b/connection/mysql_utils.go @@ -219,12 +219,12 @@ type prettyPrintedSql struct { sql string } -// String implements and interface from Stringer +// String implements and interface from Stringer. func (p prettyPrintedSql) String() string { return strings.TrimSpace(prettyPrintedSqlReplacer.Replace(p.sql)) } -// MarshalText implements an interface from TextMarshaler +// MarshalText implements an interface from TextMarshaler. func (p prettyPrintedSql) MarshalText() (text []byte, err error) { return []byte(p.String()), nil } @@ -247,7 +247,7 @@ func (p *prettyPrintedArgs) String() string { return res + " ]" } -// MarshalText implements an interface from TextMarshaler +// MarshalText implements an interface from TextMarshaler. func (p prettyPrintedArgs) MarshalText() (text []byte, err error) { return []byte(p.String()), nil } @@ -256,7 +256,7 @@ type prettyPrintedRowsAffected struct { result sql.Result } -// String implements and interface from Stringer +// String implements and interface from Stringer. func (d prettyPrintedRowsAffected) String() string { if d.result != nil { rows, errRA := d.result.RowsAffected() @@ -268,7 +268,7 @@ func (d prettyPrintedRowsAffected) String() string { return "N/A" } -// MarshalText implements an interface from TextMarshaler +// MarshalText implements an interface from TextMarshaler. func (d prettyPrintedRowsAffected) MarshalText() (text []byte, err error) { return []byte(d.String()), nil } @@ -281,7 +281,7 @@ func (e MysqlConnectionError) Error() string { return e.err } -// Returns whether the given error signals serialization failure +// isSerializationFailure returns whether the given error signals serialization failure. // https://dev.mysql.com/doc/refman/5.5/en/error-messages-server.html#error_er_lock_deadlock func isSerializationFailure(e error) bool { switch err := e.(type) { diff --git a/connection/redis.go b/connection/redis.go index e9fd40ab..b9457524 100644 --- a/connection/redis.go +++ b/connection/redis.go @@ -86,7 +86,7 @@ type RedisClient interface { type StatusCmd interface { } -// Redis wrapper including helper functions +// RDBWrapper is a redis wrapper including helper functions. type RDBWrapper struct { Rdb RedisClient ConnectedAtomic *uint32 //uint32 to be able to use atomic operations @@ -203,7 +203,7 @@ func (rdbw *RDBWrapper) WaitForConnection() { rdbw.ConnectionUpCondition.L.Unlock() } -// Wrapper for connection handling +// Publish is a wrapper for connection handling. func (rdbw *RDBWrapper) Publish(channel string, message interface{}) *redis.IntCmd { for { if !rdbw.IsConnected() { @@ -224,7 +224,7 @@ func (rdbw *RDBWrapper) Publish(channel string, message interface{}) *redis.IntC } } -// Wrapper for connection handling +// XRead is a wrapper for connection handling. func (rdbw *RDBWrapper) XRead(args *redis.XReadArgs) *redis.XStreamSliceCmd { for { if !rdbw.IsConnected() { @@ -245,7 +245,7 @@ func (rdbw *RDBWrapper) XRead(args *redis.XReadArgs) *redis.XStreamSliceCmd { } } -// Wrapper for connection handling +// XDel is a wrapper for connection handling. func (rdbw *RDBWrapper) XDel(stream string, ids ...string) *redis.IntCmd { for { if !rdbw.IsConnected() { @@ -266,7 +266,7 @@ func (rdbw *RDBWrapper) XDel(stream string, ids ...string) *redis.IntCmd { } } -// Wrapper for connection handling +// HKeys is a wrapper for connection handling. func (rdbw *RDBWrapper) HKeys(key string) *redis.StringSliceCmd { for { if !rdbw.IsConnected() { @@ -307,7 +307,7 @@ func (rdbw *RDBWrapper) HMGet(key string, fields ...string) *redis.SliceCmd { } } -// Wrapper for auto-logging and connection handling +// HGetAll is a wrapper for auto-logging and connection handling. func (rdbw *RDBWrapper) HGetAll(key string) *redis.StringStringMapCmd { for { if !rdbw.IsConnected() { @@ -339,7 +339,7 @@ func (rdbw *RDBWrapper) HGetAll(key string) *redis.StringStringMapCmd { } } -// Wrapper for auto-logging and connection handling +// TxPipelined is a wrapper for auto-logging and connection handling. func (rdbw *RDBWrapper) TxPipelined(fn func(pipeliner redis.Pipeliner) error) ([]redis.Cmder, error) { for { if !rdbw.IsConnected() { diff --git a/ha/heartbeat.go b/ha/heartbeat.go index 4730891b..73bc56cb 100644 --- a/ha/heartbeat.go +++ b/ha/heartbeat.go @@ -15,7 +15,7 @@ type Environment struct { NodeName string } -// Compute SHA1 +// Sha1bytes computes SHA1. func Sha1bytes(bytes []byte) []byte { hash := sha1.New() hash.Write(bytes) diff --git a/utils/benchmark.go b/utils/benchmark.go index f1935fbd..a2b36b73 100644 --- a/utils/benchmark.go +++ b/utils/benchmark.go @@ -14,7 +14,7 @@ type Benchmark struct { diff time.Duration } -// MarshalText implements an interface from TextMarshaler +// MarshalText implements an interface from TextMarshaler. func (b *Benchmark) MarshalText() (text []byte, err error) { return []byte(b.String()), nil } diff --git a/utils/convert.go b/utils/convert.go index 320fd326..8a31b130 100644 --- a/utils/convert.go +++ b/utils/convert.go @@ -49,14 +49,14 @@ var ( } ) -// Checksum converts the given string into a SHA1 checksum string +// Checksum converts the given string into a SHA1 checksum string. func Checksum(s string) string { hash := sha1.New() hash.Write([]byte(s)) return fmt.Sprintf("%x", hash.Sum(nil)) } -// EncodeChecksum converts a hex string to a byte array +// EncodeChecksum converts a hex string to a byte array. func EncodeChecksum(s string) []byte { c, err := hex.DecodeString(s) if err != nil { @@ -66,7 +66,7 @@ func EncodeChecksum(s string) []byte { return c } -// DecodeHexIfNotNil converts a hex string to a byte array +// DecodeHexIfNotNil converts a hex string to a byte array. func DecodeHexIfNotNil(hexStr interface{}) interface{} { if hexStr == nil { return nil @@ -75,12 +75,12 @@ func DecodeHexIfNotNil(hexStr interface{}) interface{} { return EncodeChecksum(hexStr.(string)) } -// DecodeChecksum coverts a byte array into a hex string +// DecodeChecksum coverts a byte array into a hex string. func DecodeChecksum(c []byte) string { return hex.EncodeToString(c) } -// Converts an array of notification state strings into a bit mask +// NotificationStatesToBitMask converts an array of notification state strings into a bit mask. func NotificationStatesToBitMask(states []string) int { if states == nil { return 63 @@ -93,7 +93,7 @@ func NotificationStatesToBitMask(states []string) int { return mask } -// Converts an array of notification type strings into a bit mask +// NotificationTypesToBitMask converts an array of notification type strings into a bit mask. func NotificationTypesToBitMask(types []string) int { if types == nil { return 511 @@ -114,7 +114,7 @@ func IcingaStateTypeToString(stateType float32) string { } } -//Converts a boolean we got from Redis into a DB boolean +// JSONBooleanToDBBoolean converts a boolean we got from Redis into a DB boolean. func JSONBooleanToDBBoolean(value interface{}) string { if value == "true" { return "y"