Documentation cleanup

Start each documentation block with the method or type name and move the
first paragraph into the active voice.

Author: Sean Treadway

auth.go

@@ -9,12 +9,14 @@ import (
 	"fmt"
 )
 
-// Interface to encode different SASL authentication mechanisms used during connection tuning.
+// Authentication interface provides a means for different SASL authentication
+// mechanisms to be used during connection tuning.
 type Authentication interface {
 	Mechanism() string
 	Response() string
 }
 
+// PlainAuth is a similar to Basic Auth in HTTP.
 type PlainAuth struct {
 	Username string
 	Password string

channel.go

@@ -17,9 +17,9 @@ import (
 	"time"
 )
 
-// Used in Open to specify the desired tuning parameters used during a
-// connection open handshake.  The negotiated tuning will be stored in the
-// resultant connection.
+// Config is used in Open to specify the desired tuning parameters used during
+// a connection open handshake.  The negotiated tuning will be stored in the
+// returned connection's Config field.
 type Config struct {
 	// The SASL mechanisms to try in the client request, and the successful
 	// mechanism used on the Connection object
@@ -32,8 +32,11 @@ type Config struct {
 	Heartbeat time.Duration // less than 1s interval means no heartbeats
 }
 
-// Manages the serialization and deserialization of frames from IO and
-// dispatches the frames to the appropriate channel.
+// Connection manages the serialization and deserialization of frames from IO
+// and dispatches the frames to the appropriate channel.  All RPC methods and
+// asyncronous Publishing, Delivery, Ack, Nack and Return messages are
+// multiplexed on this channel.  There must always be active receivers for
+// every asynchronous message on this connection.
 type Connection struct {
 	destructor sync.Once
 	m          sync.Mutex // writer and notify mutex
@@ -91,6 +94,12 @@ func Dial(amqp string) (*Connection, error) {
 	})
 }
 
+/*
+Open accepts an already established connection, or other io.ReadWriteCloser as
+a transport.  Use this method if you have established a TLS connection or wish
+to use your own custom transport.
+
+*/
 func Open(conn io.ReadWriteCloser, config Config) (*Connection, error) {
 	me := &Connection{
 		conn:     conn,
@@ -108,10 +117,16 @@ func (me *Connection) nextChannelId() uint16 {
 	return uint16(atomic.AddUint32(&me.sequence, 1))
 }
 
-// Listens for close events either initiated by an error accompaning a
-// connection.close method or by a normal shutdown.
-//
-// On normal shutdowns, the chan will be closed.
+/*
+NotifyClose registers a listener for close events either initiated by an error
+accompaning a connection.close method or by a normal shutdown.
+
+On normal shutdowns, the chan will be closed.
+
+To reconnect after a transport or protocol error, register a listener here and
+re-run your setup process.
+
+*/
 func (me *Connection) NotifyClose(c chan *Error) chan *Error {
 	me.m.Lock()
 	defer me.m.Unlock()
@@ -120,10 +135,10 @@ func (me *Connection) NotifyClose(c chan *Error) chan *Error {
 }
 
 /*
-Requests, and waits for the response to close the AMQP connection.
+Close requests and waits for the response to close the AMQP connection.
 
-It's advisable to use this message when publishing so to make sure that all
-kernel buffers have been flushed before exiting.
+It's advisable to use this message when publishing to ensure all kernel buffers
+have been flushed on the server and client before exiting.
 
 An error indicates that server may not have received this request to close but
 the connection should be treated as closed regardless.
@@ -349,7 +364,12 @@ func (me *Connection) isCapable(featureName string) bool {
 	return false
 }
 
-// Constructs and opens a unique channel for concurrent operations
+/*
+Channel opens a unique, concurrent server channel to process the bulk of AMQP
+messages.  Any error from methods on this receiver will render the receiver
+invalid and a new Channel should be opened.
+
+*/
 func (me *Connection) Channel() (*Channel, error) {
 	id := me.nextChannelId()
 	channel := newChannel(me, id)

connection.go

@@ -9,8 +9,9 @@ import (
 	"time"
 )
 
-// A delivery from the server to a consumer started with Queue.Consume or
-// Queue.Get.
+// Delivery captures the fields for a previously delivered message resident in
+// a queue to be delivered by the server to a consumer from Channel.Consume or
+// Channel.Get.
 type Delivery struct {
 	channel *Channel
 
@@ -88,6 +89,8 @@ func newDelivery(channel *Channel, msg messageWithContent) *Delivery {
 }
 
 /*
+Ack acknowledges that the client or server has finished work on a delivery.
+
 All deliveries in AMQP must be acknowledged.  If you called Channel.Consume
 with autoAck true then the server will be automatically ack each message and
 this method should not be called.  Otherwise, you must call Delivery.Ack after
@@ -111,7 +114,7 @@ func (me Delivery) Ack(multiple bool) error {
 }
 
 /*
-Negatively acknowledge processing of this message.
+Reject negatively acknowledge processing of this message.
 
 When requeue is true, queue this message to be delivered to a consumer on a
 different channel.  When requeue is false or the server is unable to queue this
@@ -131,17 +134,18 @@ func (me Delivery) Reject(requeue bool) error {
 }
 
 /*
-Uses the consumer identity in this delivery to cancel the consumer delegating
-to Channel.Cancel.  An error indicates the channel is closed.
+Cancel delegates to a Channel.Cancel and uses the consumer identity in this delivery to cancel the consumer.
+
+An error indicates the channel is closed.
 
 */
 func (me Delivery) Cancel(noWait bool) error {
 	return me.channel.Cancel(me.ConsumerTag, noWait)
 }
 
 /*
-RabbitMQ extension - Negatively acknowledge the delivery of message(s)
-identified by the deliveryTag.
+Nack negatively acknowledge the delivery of message(s) identified by the
+deliveryTag from either from either the client or server.
 
 When multiple is true, nack messages up to and including delivered messages up
 until the deliveryTag delivered on the same channel.

delivery.go

@@ -6,9 +6,8 @@
 /*
 AMQP 0.9.1 client with RabbitMQ extensions
 
-Start out with understanding the AMQP 0.9.1 messaging model by reviewing these
-links. Much of the terminology in this library directly relates to AMQP
-concepts.
+Understand the AMQP 0.9.1 messaging model by reviewing these links first. Much
+of the terminology in this library directly relates to AMQP concepts.
 
   Resources
 
@@ -58,6 +57,10 @@ The Notify* methods with Connection and Channel receivers model the pattern of
 asynchronous events like closes due to exceptions, or messages that are sent out
 of band from an RPC call like basic.ack or basic.flow.
 
+Any asynchronous events, including Deliveries and Publishings must always have
+a receiver until the corresponding chans are closed.  Without asynchronous
+receivers, the sychronous methods will block.
+
 Typical Use Case
 
 It's important as a client to an AMQP topology to ensure the state of the

doc.go

@@ -9,9 +9,9 @@ import (
 	"time"
 )
 
-// A flattened struct of fields returned by the server when a Publishing is
-// unable to be delivered either due to the `mandatory` flag set and no route
-// found, or `immediate` flag set and no free consumer.
+// Return captures a flattened struct of fields returned by the server when a
+// Publishing is unable to be delivered either due to the `mandatory` flag set
+// and no route found, or `immediate` flag set and no free consumer.
 type Return struct {
 	ReplyCode  uint16 // reason
 	ReplyText  string // description

return.go

@@ -23,7 +23,8 @@ var (
 	ErrUnexpectedFrame = &Error{Code: UnexpectedFrame, Reason: "unexpected frame received"}
 )
 
-// The code and reason a channel or connection has been closed by the server.
+// Error captures the code and reason a channel or connection has been closed
+// by the server.
 type Error struct {
 	Code    int    // constant code from the specification
 	Reason  string // description of the error
@@ -96,17 +97,18 @@ const (
 	flagReserved1       = 0x0004
 )
 
-// Current state of the queue on the server returned from Channel.QueueDeclare or
-// Channel.QueueInspect.
+// Queue captures the current server state of the queue on the server returned
+// from Channel.QueueDeclare or Channel.QueueInspect.
 type Queue struct {
 	Name      string // server confirmed or generated name
 	Messages  int    // count of messages not awaiting acknowledgment
 	Consumers int    // number of consumers receiving deliveries
 }
 
-// A published message from the client to the server.  The fields outside of
-// the Headers table included in this struct mirror the underlying fields in
-// the content frame.  They use native types for convienence and efficiency.
+// Publishing captures the client message sent to the server.  The fields
+// outside of the Headers table included in this struct mirror the underlying
+// fields in the content frame.  They use native types for convienence and
+// efficiency.
 type Publishing struct {
 	// Application or exchange specific fields,
 	// the headers exchange will inspect this field.
@@ -126,17 +128,18 @@ type Publishing struct {
 	UserId          string    // creating user id - ex: "guest"
 	AppId           string    // creating application id
 
+	// The application specific payload of the message
 	Body []byte
 }
 
-// The golang type that matches the amqp type.  Scale is the number of decimal digits
-// Scale == 2, Value == 12345, Decimal == 123.45
+// Decimal matches the AMQP decimal type.  Scale is the number of decimal
+// digits Scale == 2, Value == 12345, Decimal == 123.45
 type Decimal struct {
 	Scale uint8
 	Value int32
 }
 
-// The amqp type that represents a string to field.  Most Go types are supported in
+// Table matches the amqp table type for string to field mappings.  Most Go types are supported in
 // table serialization.
 type Table map[string]interface{}