Add godoc for sync producer and async producer mock types.

mocks/producer.go

@@ -7,6 +7,8 @@ import (
 	"github.com/Shopify/sarama"
 )
 
+// A simple interafce that includes the testing.T methods we use to report
+// expectation violations when using the mock objects.
 type TestReporter interface {
 	Errorf(string, ...interface{})
 }
@@ -20,6 +22,10 @@ type producerExpectation struct {
 	Result error
 }
 
+// Producer implements sarama's Producer interface for testing purposes.
+// Before you can send messages to it's Input channel, you have to set expectations
+// so it knows how to handle the input. This way you can easily test success and
+// failure scenarios.
 type Producer struct {
 	l            sync.Mutex
 	expectations []*producerExpectation
@@ -29,6 +35,10 @@ type Producer struct {
 	errors       chan *sarama.ProducerError
 }
 
+// NewProducer instantiates a new Producer mock. The t argument should
+// be the *testing.T instance of your test method. An error will be written to it if
+// an expectation is violated. The config argument is used to determine whether it
+// should ack successes on the Successes channel.
 func NewProducer(t TestReporter, config *sarama.Config) *Producer {
 	if config == nil {
 		config = sarama.NewConfig()
@@ -78,38 +88,62 @@ func NewProducer(t TestReporter, config *sarama.Config) *Producer {
 	return mp
 }
 
-// Implement KafkaProducer interface
+////////////////////////////////////////////////
+// Implement Producer interface
+////////////////////////////////////////////////
 
+// AsyncClose corresponds with the AsyncClose method of sarama's Producer implementation.
+// By closing a mock producer, you also tell it that no more input will be provided, so it will
+// write an error to the test state if there's any remaining expectations.
 func (mp *Producer) AsyncClose() {
 	close(mp.input)
 }
 
+// Close corresponds with the Close method of sarama's Producer implementation.
+// By closing a mock producer, you also tell it that no more input will be provided, so it will
+// write an error to the test state if there's any remaining expectations.
 func (mp *Producer) Close() error {
 	mp.AsyncClose()
 	<-mp.closed
 	return nil
 }
 
+// Input corresponds with the Input method of sarama's Producer implementation.
+// You have to set expectations on the mock producer before writing messages to the Input
+// channel, so it knows how to handle them. If there is no more remaining expectations and
+// a messages is written to the Input channel, the mock producer will write an error to the test
+// state object.
 func (mp *Producer) Input() chan<- *sarama.ProducerMessage {
 	return mp.input
 }
 
+// Successes corresponds with the Successes method of sarama's Producer implementation.
 func (mp *Producer) Successes() <-chan *sarama.ProducerMessage {
 	return mp.successes
 }
 
+// Errors corresponds with the Errors method of sarama's Producer implementation.
 func (mp *Producer) Errors() <-chan *sarama.ProducerError {
 	return mp.errors
 }
 
+////////////////////////////////////////////////
 // Setting expectations
+////////////////////////////////////////////////
 
+// ExpectInputAndSucceed sets an expectation on the mock producer that a message will be provided
+// on the input channel. The mock producer will handle the message as if it is produced successfully,
+// i.e. it will make it available on the Successes channel if the Producer.AckSuccesses setting
+// is set to true.
 func (mp *Producer) ExpectInputAndSucceed() {
 	mp.l.Lock()
 	defer mp.l.Unlock()
 	mp.expectations = append(mp.expectations, &producerExpectation{Result: errProduceSuccess})
 }
 
+// ExpectInputAndFail sets an expectation on the mock producer that a message will be provided
+// on the input channel. The mock producer will handle the message as if it failed to produce
+// successfully. This means it will make a ProducerError available on the Errors channel.
 func (mp *Producer) ExpectInputAndFail(err error) {
 	mp.l.Lock()
 	defer mp.l.Unlock()

mocks/sync_producer.go

@@ -5,6 +5,10 @@ import (
 	"sync"
 )
 
+// SyncProducer implements sarama's SyncProducer interface for testing purposes.
+// Before you can use it, you have to set expectations on the mock SyncProducer
+// to tell it how to handle calls to SendMessage, so you can easily test success
+// and failure scenarios.
 type SyncProducer struct {
 	l            sync.Mutex
 	t            TestReporter
@@ -12,6 +16,10 @@ type SyncProducer struct {
 	lastOffset   int64
 }
 
+// NewSyncProducer instantiates a new SyncProducer mock. The t argument should
+// be the *testing.T instance of your test method. An error will be written to it if
+// an expectation is violated. The config argument is currently unused, but is
+// maintained to be compatible with the async Producer.
 func NewSyncProducer(t TestReporter, config *sarama.Config) *SyncProducer {
 	return &SyncProducer{
 		t:            t,
@@ -19,6 +27,14 @@ func NewSyncProducer(t TestReporter, config *sarama.Config) *SyncProducer {
 	}
 }
 
+////////////////////////////////////////////////
+// Implement SyncProducer interface
+////////////////////////////////////////////////
+
+// SendMessage corresponds with the SendMessage method of sarama's SyncProducer implementation.
+// You have to set expectations on the mock producer before calling SendMessage, so it knows
+// how to handle them. If there is no more remaining expectations when SendMessage is called,
+// the mock producer will write an error to the test state object.
 func (sp *SyncProducer) SendMessage(topic string, key, value sarama.Encoder) (partition int32, offset int64, err error) {
 	sp.l.Lock()
 	defer sp.l.Unlock()
@@ -39,6 +55,9 @@ func (sp *SyncProducer) SendMessage(topic string, key, value sarama.Encoder) (pa
 	}
 }
 
+// Close corresponds with the Close method of sarama's SyncProducer implementation.
+// By closing a mock syncproducer, you also tell it that no more SendMessage calls will follow,
+// so it will write an error to the test state if there's any remaining expectations.
 func (sp *SyncProducer) Close() error {
 	sp.l.Lock()
 	defer sp.l.Unlock()
@@ -50,12 +69,22 @@ func (sp *SyncProducer) Close() error {
 	return nil
 }
 
+////////////////////////////////////////////////
+// Setting expectations
+////////////////////////////////////////////////
+
+// ExpectSendMessageAndSucceed sets an expectation on the mock producer that SendMessage will be
+// called. The mock producer will handle the message as if it produced successfully, i.e. by
+// returning a valid partition, and offset, and a nil error.
 func (sp *SyncProducer) ExpectSendMessageAndSucceed() {
 	sp.l.Lock()
 	defer sp.l.Unlock()
 	sp.expectations = append(sp.expectations, &producerExpectation{Result: errProduceSuccess})
 }
 
+// ExpectSendMessageAndFail sets an expectation on the mock producer that SendMessage will be
+// called. The mock producer will handle the message as if it failed to produce
+// successfully, i.e. by returning the provided error.
 func (sp *SyncProducer) ExpectSendMessageAndFail(err error) {
 	sp.l.Lock()
 	defer sp.l.Unlock()