update: add comments, change several functions's name

cnf/conf.go

@@ -1,10 +1,9 @@
-package cnf
-
-/**
-	DEPRECATED:
+// Copyright wenstudio@asia.com
 
-	Read config file from dist. use viper which support many types of configure files.
- */
+// Please use viper package directly.
+//
+// Deprecated: use viper
+package cnf
 
 //import (
 //	"github.com/spf13/viper"
@@ -20,4 +19,4 @@ package cnf
 //		return err
 //	}
 //	return nil
-//}
+//}

doc.go

@@ -0,0 +1,6 @@
+// Copyright: 2020 wenstudio@asia.com
+
+// Ordinary golang project skeleton
+//
+// kettle
+package kettle

etcd/etcd.go

@@ -127,7 +127,7 @@ func (self *EtcdClient) WatchRange(from, to string) clientv3.WatchChan {
 	return self.c.Watch(context.Background(), from, clientv3.WithRange(to))
 }
 
-//// maintain
+//// maintainance
 func (self *EtcdClient) Compact(rev int64) error {
 	ctx, cancel := context.WithTimeout(context.Background(), self.timeout)
 	defer cancel()

utl/bufPool.go

@@ -12,11 +12,14 @@ func init() {
 	DefBufPool = NewBufPool(uint32(1024 * 2))
 }
 
+// Pool of buffer
 type BufPool struct {
 	p    *sync.Pool
 	size uint32
 }
 
+// Create a pool of buffers.
+// the size of each buffer is specified by `size`
 func NewBufPool(size uint32) *BufPool {
 	return &BufPool{
 		p: &sync.Pool{
@@ -28,14 +31,17 @@ func NewBufPool(size uint32) *BufPool {
 	}
 }
 
+// Get a sized buffer from pool
 func (self *BufPool) Get() []byte {
 	return self.p.Get().([]byte)
 }
 
+// Get default buffer size of the pool. which is passed by NewBufPool()
 func (self *BufPool) GetSize() uint32 {
 	return self.size
 }
 
+// Return the buffer retrieve by Get()
 func (self *BufPool) Put(data []byte) {
 	self.p.Put(data)
 }

utl/catpcha.go

@@ -8,11 +8,13 @@ var (
 	store = base64Captcha.DefaultMemStore
 )
 
-type DigitCatpcha struct {
+// Used for generating and verify the digital captcha
+type DigitCaptcha struct {
 	h *base64Captcha.Captcha
 }
 
-func NewDigitCatpcha(length int) *DigitCatpcha {
+// Initializer. length is the length of the digitals
+func NewDigitCatpcha(length int) *DigitCaptcha {
 	driver := &base64Captcha.DriverDigit{
 		Height:   80,
 		Width:    240,
@@ -20,16 +22,23 @@ func NewDigitCatpcha(length int) *DigitCatpcha {
 		MaxSkew:  0.7,
 		DotCount: 80,
 	}
-	return &DigitCatpcha{
+	return &DigitCaptcha{
 		h: base64Captcha.NewCaptcha(driver, store),
 	}
 }
 
-func (self *DigitCatpcha) Gen() (id, b64 string, err error) {
+// Generate a new captcha image
+//
+// return
+// 		id: is the id of the new captcha image
+//		b64: captcha image in base64 format
+// 		err: any error
+func (self *DigitCaptcha) Gen() (id, b64 string, err error) {
 	id, b64, err = self.h.Generate()
 	return
 }
 
-func (self *DigitCatpcha) Verify(id, value string) bool {
+// Verify if the user input is the same as digits in captcha.
+func (self *DigitCaptcha) Verify(id, value string) bool {
 	return store.Verify(id, value, true)
 }

utl/job.go

@@ -1,28 +1,32 @@
 package utl
 
-/**
-A job should be callable
-
-so there may be 2 types of jobs at least
-*/
-
+// Job interface
 type IJob interface {
 	Exec(interface{}) error
 }
 
+// Job in function style.
+// It also implements the IJob interface.
 type IJobFn func(interface{}) error
-type TJobChan chan *Job
-type TJobPool chan TJobChan
 
 func (fn IJobFn) Exec(inf interface{}) error {
 	return fn(inf)
 }
 
+// Type of chan of Jobs
+type TJobChan chan *Job
+
+// Chan of Job chan
+type TJobPool chan TJobChan
+
+// Job object
+// composed with a job interface and its parameters
 type Job struct {
 	param interface{}
 	job   IJob
 }
 
+// Job constructor
 func NewJob(job IJob, param interface{}) *Job {
 	return &Job{
 		param: param,
@@ -30,6 +34,7 @@ func NewJob(job IJob, param interface{}) *Job {
 	}
 }
 
+// Job executor
 func (self *Job) Do() error {
 	return self.job.Exec(self.param)
 }

utl/rand.go

@@ -10,6 +10,7 @@ var (
 	r = rand.New(s)
 )
 
+// Return a random string composed with digits, its length is specified by sz
 func RandNumString(sz int) string {
 	b := make([]byte, sz)
 	for i := 0; i < sz; i++ {
@@ -18,6 +19,7 @@ func RandNumString(sz int) string {
 	return string(b)
 }
 
+// Return a random string composed with digital and character, its length is specified by sz.
 func RandAlphaStr(sz int) string {
 	starts := []int{0x30, 0x41, 0x61}
 	lens := []int{10, 26, 26}
@@ -29,6 +31,7 @@ func RandAlphaStr(sz int) string {
 	return string(b)
 }
 
+// Get
 func RandInt(m, n int) int {
 	if m > n {
 		return RandInt(n, m)

utl/rand_test.go

@@ -21,7 +21,7 @@ func TestRandNumString(t *testing.T) {
 
 func TestRandAlphaStr(t *testing.T) {
 	s := RandAlphaStr(6)
-	t.Log(s)
+	t.Logf("s:%v", s)
 }
 
 func TestRandIntn(t *testing.T) {

utl/workerPool.go

@@ -4,8 +4,10 @@ import (
 	"time"
 )
 
+// WorkPool Options
 type WorkPoolOption func(*WorkPool)
 
+// size of pool
 func WithWorkPoolSize(size int) WorkPoolOption {
 	return func(wp *WorkPool) {
 		if size < 1 {
@@ -25,11 +27,12 @@ func WithWorkPoolLifetime(lifetime time.Duration) WorkPoolOption {
 }
 
 type WorkPool struct {
-	goChan   TJobPool
+	chPool   TJobPool
 	size     int
 	lifetime time.Duration
 }
 
+// constructor. return a WorkPool instance by options
 func NewWorkPool(options ...WorkPoolOption) *WorkPool {
 	wp := &WorkPool{}
 
@@ -37,14 +40,14 @@ func NewWorkPool(options ...WorkPoolOption) *WorkPool {
 		opt(wp)
 	}
 
-	wp.goChan = make(TJobPool, wp.size)
+	wp.chPool = make(TJobPool, wp.size)
 
 	return wp
 }
 
 func (wp *WorkPool) Put(job *Job) {
-	for len(wp.goChan) > 0 {
-		jobChan := <-wp.goChan
+	for len(wp.chPool) > 0 {
+		jobChan := <-wp.chPool
 		if jobChan == nil {
 			continue
 		}
@@ -54,7 +57,8 @@ func (wp *WorkPool) Put(job *Job) {
 			jobChan <- job
 			return
 		}
-	}
+	} // for
+
 	jobChan := make(TJobChan, 1)
 	jobChan <- job
 	go wp.do(jobChan)
@@ -87,8 +91,8 @@ func (wp *WorkPool) do(one TJobChan) {
 			timer.Reset(time.Second * 10)
 		}
 		// reuse
-		if len(wp.goChan) < wp.size {
-			wp.goChan <- one
+		if len(wp.chPool) < wp.size {
+			wp.chPool <- one
 		}
 	} //for
 }