Merge pull request #654 from Shopify/doc-update

Update a bunch of docs

sarama.go

@@ -1,19 +1,25 @@
 /*
-Package sarama provides client libraries for the Kafka protocol (versions 0.8 and later). The AsyncProducer object
-is the high-level API for producing messages asynchronously; the SyncProducer provides a blocking API for the same purpose.
-The Consumer object is the high-level API for consuming messages. The Client object provides metadata
-management functionality that is shared between the higher-level objects.
-
-Note that Sarama's Consumer type does not currently support automatic consumer-group rebalancing and offset tracking.
-For Zookeeper-based tracking (Kafka 0.8.2 and earlier), the https://github.com/wvanbergen/kafka library
-builds on Sarama to add this support. For Kafka-based tracking (Kafka 0.9 and later), the
-https://github.com/bsm/sarama-cluster library builds on Sarama to add this support.
+Package sarama is a pure Go client library for dealing with Apache Kafka (versions 0.8 and later). It includes a high-level
+API for easily producing and consuming messages, and a low-level API for controlling bytes on the wire when the high-level
+API is insufficient. Usage examples for the high-level APIs are provided inline with their full documentation.
+
+To produce messages, use either the AsyncProducer or the SyncProducer. The AsyncProducer accepts messages on a channel
+and produces them asynchronously in the background as efficiently as possible; it is preferred in most cases.
+The SyncProducer provides a method which will block until Kafka acknowledges the message as produced. This can be
+useful but comes with two caveats: it will generally be less efficient, and the actual durability guarantees
+depend on the configured value of `Producer.RequiredAcks`. There are configurations where a message acknowledged by the
+SyncProducer can still sometimes be lost.
+
+To consume messages, use the Consumer. Note that Sarama's Consumer implementation does not currently support automatic
+consumer-group rebalancing and offset tracking. For Zookeeper-based tracking (Kafka 0.8.2 and earlier), the
+https://github.com/wvanbergen/kafka library builds on Sarama to add this support. For Kafka-based tracking (Kafka 0.9
+and later), the https://github.com/bsm/sarama-cluster library builds on Sarama to add this support.
 
 For lower-level needs, the Broker and Request/Response objects permit precise control over each connection
-and message sent on the wire.
-
-The Request/Response objects and properties are mostly undocumented, as they line up exactly with the
-protocol fields documented by Kafka at https://cwiki.apache.org/confluence/display/KAFKA/A+Guide+To+The+Kafka+Protocol
+and message sent on the wire; the Client provides higher-level metadata management that is shared between
+the producers and the consumer. The Request/Response objects and properties are mostly undocumented, as they line up
+exactly with the protocol fields documented by Kafka at
+https://cwiki.apache.org/confluence/display/KAFKA/A+Guide+To+The+Kafka+Protocol
 */
 package sarama
 

sync_producer.go

@@ -2,9 +2,13 @@ package sarama
 
 import "sync"
 
-// SyncProducer publishes Kafka messages. It routes messages to the correct broker, refreshing metadata as appropriate,
-// and parses responses for errors. You must call Close() on a producer to avoid leaks, it may not be garbage-collected automatically when
-// it passes out of scope.
+// SyncProducer publishes Kafka messages, blocking until they have been acknowledged. It routes messages to the correct
+// broker, refreshing metadata as appropriate, and parses responses for errors. You must call Close() on a producer
+// to avoid leaks, it may not be garbage-collected automatically when it passes out of scope.
+//
+// The SyncProducer comes with two caveats: it will generally be less efficient than the AsyncProducer, and the actual
+// durability guarantee provided when a message is acknowledged depend on the configured value of `Producer.RequiredAcks`.
+// There are configurations where a message acknowledged by the SyncProducer can still sometimes be lost.
 type SyncProducer interface {
 
 	// SendMessage produces a given message, and returns only when it either has