Add Godoc

README.md

@@ -3,15 +3,13 @@
 [Golang](http://golang.org/) client for [Disque](https://github.com/antirez/disque), the Persistent Distributed Job Priority Queue.
 
 - **Persistent** - Jobs can be either in-memory or persisted on disk<sup>[[1]](https://github.com/antirez/disque#disque-and-disk-persistence)</sup>.
-- **Distributed** - Multiple producers, multiple consumers.
-- **Job Priority Queue** - Multiple queues. Consumers Dequeue() from higher priority queues first.
-- **Fault tolerant** - Jobs must be replicated to N nodes before Enqueue() returns. Jobs must be ACKed or they'll be re-queued automatically within a specified Retry Timeout.
+- **Distributed** - Disque pool. Multiple producers, multiple consumers.
+- **Job Priority Queue** - Multiple queues. Consumers `Get()` from higher priority queues first.
+- **Fault tolerant** - Jobs must be replicated to N nodes before `Add()` returns. Jobs must be `ACK()`ed after `Get()` or they'll be re-queued automatically within a specified `RetryAfter` timeout.
 
 [![GoDoc](https://godoc.org/github.com/goware/disque?status.png)](https://godoc.org/github.com/goware/disque)
 [![Travis](https://travis-ci.org/goware/disque.svg?branch=master)](https://travis-ci.org/goware/disque)
 
-**This project is in early development stage. You can expect changes to both functionality and the API. Feedback welcome!**
-
 ## Producer
 
 ```go
@@ -60,18 +58,18 @@ func main() {
 }
 ```
 
-## Custom config (Timeout, Replicate, Delay, Retry, TTL, MaxLen)
+## Config (Timeout, Replicate, Delay, Retry, TTL, MaxLen)
 
 ```go
 jobs, _ := disque.Connect("127.0.0.1:7711")
 
 config := disque.Config{
-    Timeout:    500 * time.Second, // Each operation will fail after 1s. It blocks by default.
-    Replicate:  2,                 // Add(): Replicate job to at least two nodes before return.
-    Delay:      time.Hour,         // Add(): Schedule the job - enqueue after one hour.
-    RetryAfter: time.Minute,       // Add(): Re-queue job after 1min (time between Get() and Ack()).
-    TTL:        24 * time.Hour,    // Add(): Remove the job from queue after one day.
-    MaxLen:     1000,              // Add(): Fail if there are more than 1000 jobs in the queue.
+    Timeout:    time.Second,    // Each operation will fail after 1s. It blocks by default.
+    Replicate:  2,              // Add(): Replicate job to at least two nodes before return.
+    Delay:      time.Hour,      // Add(): Schedule the job - enqueue after one hour.
+    RetryAfter: time.Minute,    // Add(): Re-queue job after 1min (time between Get() and Ack()).
+    TTL:        24 * time.Hour, // Add(): Remove the job from queue after one day.
+    MaxLen:     1000,           // Add(): Fail if there are more than 1000 jobs in the queue.
 }
 
 // Apply globally.

config.go

@@ -2,49 +2,58 @@ package disque
 
 import "time"
 
+// Config represents Disque configuration for certain operations.
 type Config struct {
-	Timeout    time.Duration
-	Replicate  int
-	Delay      time.Duration
-	RetryAfter time.Duration
-	TTL        time.Duration
-	MaxLen     int
+	Timeout    time.Duration // Each operation will fail after a specified timeout. Blocks by default.
+	Replicate  int           // Add(): Replicate job to at least N nodes before return.
+	Delay      time.Duration // Add(): Schedule the job - enqueue after a specified time.
+	RetryAfter time.Duration // Add(): Re-queue job after a specified time (between Get() and Ack()).
+	TTL        time.Duration // Add(): Remove the job from queue after a specified time.
+	MaxLen     int           // Add(): Fail if there are more than N jobs in the queue.
 }
 
+// Use applies given config to every subsequent operation of this connection.
 func (conn *Conn) Use(conf Config) *Conn {
 	conn.conf = conf
 	return conn
 }
 
+// With applies given config to a single operation.
 func (conn *Conn) With(conf Config) *Conn {
 	return &Conn{pool: conn.pool, conf: conf}
 }
 
+// With applies Timeout to a single operation.
 func (conn *Conn) Timeout(timeout time.Duration) *Conn {
 	conn.conf.Timeout = timeout
 	return &Conn{pool: conn.pool, conf: conn.conf}
 }
 
+// With applies Replicate to a single operation.
 func (conn *Conn) Replicate(replicate int) *Conn {
 	conn.conf.Replicate = replicate
 	return &Conn{pool: conn.pool, conf: conn.conf}
 }
 
+// With applies Delay to a single operation.
 func (conn *Conn) Delay(delay time.Duration) *Conn {
 	conn.conf.Delay = delay
 	return &Conn{pool: conn.pool, conf: conn.conf}
 }
 
+// With applies RetryAfter to a single operation.
 func (conn *Conn) RetryAfter(after time.Duration) *Conn {
 	conn.conf.RetryAfter = after
 	return &Conn{pool: conn.pool, conf: conn.conf}
 }
 
+// With applies TTL to a single operation.
 func (conn *Conn) TTL(ttl time.Duration) *Conn {
 	conn.conf.TTL = ttl
 	return &Conn{pool: conn.pool, conf: conn.conf}
 }
 
+// With applies MaxLen to a single operation.
 func (conn *Conn) MaxLen(maxlen int) *Conn {
 	conn.conf.MaxLen = maxlen
 	return &Conn{pool: conn.pool, conf: conn.conf}

disque.go

@@ -9,11 +9,13 @@ import (
 	"github.com/garyburd/redigo/redis"
 )
 
+// Conn represent a connection to a Disque Pool.
 type Conn struct {
 	pool *redis.Pool
 	conf Config
 }
 
+// Connect creates a connection to a given Disque Pool.
 func Connect(address string, extra ...string) (*Conn, error) {
 	pool := &redis.Pool{
 		MaxIdle:     64,
@@ -36,10 +38,12 @@ func Connect(address string, extra ...string) (*Conn, error) {
 	return &Conn{pool: pool}, nil
 }
 
+// Close closes connection to the Disque Pool.
 func (conn *Conn) Close() {
 	conn.pool.Close()
 }
 
+// Ping returns nil if Disque
 func (conn *Conn) Ping() error {
 	sess := conn.pool.Get()
 	defer sess.Close()
@@ -50,17 +54,18 @@ func (conn *Conn) Ping() error {
 	return nil
 }
 
-// Eh, none of the following builds successfully:
+// do is a helper function that workarounds redigo/redis API flaws
+// with reflect pkg.
 //
-//   reply, err := sess.Do("GETJOB", "FROM", queue, redis.Args{})
-//   reply, err := sess.Do("GETJOB", "FROM", queue, redis.Args{}...)
-//   reply, err := sess.Do("GETJOB", "FROM", queue, extraQueues)
-//   reply, err := sess.Do("GETJOB", "FROM", queue, extraQueues...)
+// None of the following builds successfully:
 //
-//   > build error:
-//   > too many arguments in call to sess.Do
+// reply, err := sess.Do("GETJOB", "FROM", queue, redis.Args{})
+// reply, err := sess.Do("GETJOB", "FROM", queue, redis.Args{}...)
+// reply, err := sess.Do("GETJOB", "FROM", queue, extraQueues)
+// reply, err := sess.Do("GETJOB", "FROM", queue, extraQueues...)
+//
+// > Error: "too many arguments in call to sess.Do"
 //
-// So.. let's work around this with reflect pkg.
 func (conn *Conn) do(args []interface{}) (interface{}, error) {
 	sess := conn.pool.Get()
 	defer sess.Close()
@@ -91,6 +96,7 @@ func (conn *Conn) do(args []interface{}) (interface{}, error) {
 	return reply, nil
 }
 
+// Add enqueues new Job with specified data to a given queue.
 func (conn *Conn) Add(data string, queue string) (*Job, error) {
 	args := []interface{}{
 		"ADDJOB",
@@ -144,6 +150,8 @@ func (conn *Conn) Add(data string, queue string) (*Job, error) {
 	}, nil
 }
 
+// Get returns the first available job from the highest priority
+// queue (left-to-right).
 func (conn *Conn) Get(queues ...string) (*Job, error) {
 	if len(queues) == 0 {
 		return nil, errors.New("expected at least one queue")
@@ -195,6 +203,7 @@ func (conn *Conn) Get(queues ...string) (*Job, error) {
 	}, nil
 }
 
+// Ack acknowledges (dequeues) the job from its job queue.
 func (conn *Conn) Ack(job *Job) error {
 	sess := conn.pool.Get()
 	defer sess.Close()
@@ -205,6 +214,7 @@ func (conn *Conn) Ack(job *Job) error {
 	return nil
 }
 
+// Nack re-queues job into its job queue.
 // Native NACKJOB discussed upstream at https://github.com/antirez/disque/issues/43.
 func (conn *Conn) Nack(job *Job) error {
 	sess := conn.pool.Get()
@@ -216,6 +226,7 @@ func (conn *Conn) Nack(job *Job) error {
 	return nil
 }
 
+// Wait waits for the job to finish (blocks until it's ACKed).
 // Native WAITJOB discussed upstream at https://github.com/antirez/disque/issues/43.
 func (conn *Conn) Wait(job *Job) error {
 	sess := conn.pool.Get()

job.go

 package disque
 
+// Job represents job (and its data) belonging to a queue.
 type Job struct {
 	ID    string
 	Data  string