Merge pull request #835 from Shopify/tweak-close-docs

Tweak documentation of Close/AsyncClose methods

async_producer.go

@@ -17,17 +17,16 @@ import (
 // scope.
 type AsyncProducer interface {
 
-	// AsyncClose triggers a shutdown of the producer, flushing any messages it may
+	// AsyncClose triggers a shutdown of the producer. The shutdown has completed
-	// have buffered. The shutdown has completed when both the Errors and Successes
+	// when both the Errors and Successes channels have been closed. When calling
-	// channels have been closed. When calling AsyncClose, you *must* continue to
+	// AsyncClose, you *must* continue to read from those channels in order to
-	// read from those channels in order to drain the results of any messages in
+	// drain the results of any messages in flight.
-	// flight.
 	AsyncClose()
 
-	// Close shuts down the producer and flushes any messages it may have buffered.
+	// Close shuts down the producer and waits for any buffered messages to be
-	// You must call this function before a producer object passes out of scope, as
+	// flushed. You must call this function before a producer object passes out of
-	// it may otherwise leak memory. You must call this before calling Close on the
+	// scope, as it may otherwise leak memory. You must call this before calling
-	// underlying client.
+	// Close on the underlying client.
 	Close() error
 
 	// Input is the input channel for the user to write messages to that they

sync_producer.go

@@ -25,10 +25,10 @@ type SyncProducer interface {
 	// SendMessages will return an error.
 	SendMessages(msgs []*ProducerMessage) error
 
-	// Close shuts down the producer and flushes any messages it may have buffered.
+	// Close shuts down the producer and waits for any buffered messages to be
-	// You must call this function before a producer object passes out of scope, as
+	// flushed. You must call this function before a producer object passes out of
-	// it may otherwise leak memory. You must call this before calling Close on the
+	// scope, as it may otherwise leak memory. You must call this before calling
-	// underlying client.
+	// Close on the underlying client.
 	Close() error
 }