[ci skip] Update docs

asynq.go

@@ -16,14 +16,14 @@ type Task struct {
 	// Type indicates the type of task to be performed.
 	Type string
 
-	// Payload holds data needed to process the task.
+	// Payload holds data needed to perform the task.
 	Payload Payload
 }
 
-// NewTask returns a new instance of a task given a task type and payload.
+// NewTask returns a new Task. The typename and payload argument set Type
+// and Payload field respectively.
 //
-// Since payload data gets serialized to JSON, the payload values must be
-// composed of JSON supported data types.
+// The payload must be serializable to JSON.
 func NewTask(typename string, payload map[string]interface{}) *Task {
 	return &Task{
 		Type:    typename,
@@ -34,17 +34,20 @@ func NewTask(typename string, payload map[string]interface{}) *Task {
 // RedisConnOpt is a discriminated union of redis-client-option types.
 //
 // RedisConnOpt represents a sum of following types:
+//
 // RedisClientOpt | *RedisClientOpt | RedisFailoverClientOpt | *RedisFailoverClientOpt
+//
+// Passing unexpected type to a RedisConnOpt variable can cause panic.
 type RedisConnOpt interface{}
 
-// RedisClientOpt is used to specify redis client options to connect
-// to a redis server running as a stand alone instance.
+// RedisClientOpt is used to create a redis client that connects
+// to a redis server directly.
 type RedisClientOpt struct {
 	// Network type to use, either tcp or unix.
 	// Default is tcp.
 	Network string
 
-	// Redis server address in the format 'host:port'.
+	// Redis server address in "host:port" format.
 	Addr string
 
 	// Redis server password.
@@ -63,12 +66,14 @@ type RedisClientOpt struct {
 	TLSConfig *tls.Config
 }
 
-// RedisFailoverClientOpt is used to specify redis failover client.
+// RedisFailoverClientOpt is used to creates a redis client that talks
+// to redis sentinels for service discovery and has automatic failover
+// capability.
 type RedisFailoverClientOpt struct {
 	// Redis master name that monitored by sentinels.
 	MasterName string
 
-	// Addresses of sentinels in the form "host:port".
+	// Addresses of sentinels in "host:port" format.
 	// Use at least three sentinels to avoid problems described in
 	// https://redis.io/topics/sentinel.
 	SentinelAddrs []string

background.go

@@ -21,10 +21,10 @@ import (
 
 // Background is responsible for managing the background-task processing.
 //
-// Background manages background queues to process tasks and retry if
-// necessary. If the processing of a task is unsuccessful, background will
-// schedule it for a retry with an exponential backoff until either the task
-// gets processed successfully or it exhausts its max retry count.
+// Background manages task queues to process tasks.
+// If the processing of a task is unsuccessful, background will
+// schedule it for a retry until either the task gets processed successfully
+// or it exhausts its max retry count.
 //
 // Once a task exhausts its retries, it will be moved to the "dead" queue and
 // will be kept in the queue for some time until a certain condition is met
@@ -41,7 +41,7 @@ type Background struct {
 
 // Config specifies the background-task processing behavior.
 type Config struct {
-	// Maximum number of concurrent workers to process tasks.
+	// Maximum number of concurrent processing of tasks.
 	//
 	// If set to zero or negative value, NewBackground will overwrite the value to one.
 	Concurrency int
@@ -92,7 +92,7 @@ var defaultQueueConfig = map[string]uint{
 	base.DefaultQueueName: 1,
 }
 
-// NewBackground returns a new Background instance given a redis client
+// NewBackground returns a new Background given a redis connection option
 // and background processing configuration.
 func NewBackground(r RedisConnOpt, cfg *Config) *Background {
 	n := cfg.Concurrency

client.go

@@ -23,13 +23,13 @@ type Client struct {
 	rdb *rdb.RDB
 }
 
-// NewClient and returns a new Client given a redis configuration.
+// NewClient and returns a new Client given a redis connection option.
 func NewClient(r RedisConnOpt) *Client {
 	rdb := rdb.NewRDB(createRedisClient(r))
 	return &Client{rdb}
 }
 
-// Option specifies the processing behavior for the associated task.
+// Option specifies the task processing behavior.
 type Option interface{}
 
 // Internal option representations.
@@ -49,7 +49,7 @@ func MaxRetry(n int) Option {
 	return retryOption(n)
 }
 
-// Queue returns an option to specify which queue to enqueue the task into.
+// Queue returns an option to specify the queue to enqueue the task into.
 //
 // Queue name is case-insensitive and the lowercased version is used.
 func Queue(name string) Option {
@@ -87,10 +87,10 @@ const (
 // Schedule registers a task to be processed at the specified time.
 //
 // Schedule returns nil if the task is registered successfully,
-// otherwise returns non-nil error.
+// otherwise returns a non-nil error.
 //
 // opts specifies the behavior of task processing. If there are conflicting
-// Option the last one overrides the ones before.
+// Option values the last one overrides others.
 func (c *Client) Schedule(task *Task, processAt time.Time, opts ...Option) error {
 	opt := composeOptions(opts...)
 	msg := &base.TaskMessage{

doc.go

@@ -50,8 +50,6 @@ Example of a type that implements the Handler interface.
         case "send_email":
             id, err := task.Payload.GetInt("user_id")
             // send email
-        case "generate_thumbnail":
-            // generate thumbnail image
         //...
         default:
             return fmt.Errorf("unexpected task type %q", task.Type)

payload.go

@@ -11,7 +11,7 @@ import (
 	"github.com/spf13/cast"
 )
 
-// Payload is an arbitrary data needed for task execution.
+// Payload holds arbitrary data needed for task execution.
 type Payload struct {
 	data map[string]interface{}
 }