Fix go vet issues: example tests, returning a mutex copy (#783)

Example tests are renamed to fit required naming conventions. This
caused them to be relocated in generated docs.

Also, a problem with writer.newBatchQueue is fixed; in order to avoid an
unnecessary copy of a newly created object holding a mutex, the mutex
field within batchQueue is now a pointer, so that copying on return
doesn't copy the mutex itself. The same treatment is needed for the cond
field; the same no-copy rule applies to it.

Author: bhavanki

example_consumergroup_test.go

@@ -8,7 +8,7 @@ import (
 	"github.com/segmentio/kafka-go"
 )
 
-func ExampleConsumerGroupParallelReaders() {
+func ExampleGeneration_Start_consumerGroupParallelReaders() {
 	group, err := kafka.NewConsumerGroup(kafka.ConsumerGroupConfig{
 		ID:      "my-group",
 		Brokers: []string{"kafka:9092"},
@@ -60,7 +60,7 @@ func ExampleConsumerGroupParallelReaders() {
 	}
 }
 
-func ExampleConsumerGroupOverwriteOffsets() {
+func ExampleGeneration_CommitOffsets_overwriteOffsets() {
 	group, err := kafka.NewConsumerGroup(kafka.ConsumerGroupConfig{
 		ID:      "my-group",
 		Brokers: []string{"kafka:9092"},

example_groupbalancer_test.go

@@ -10,11 +10,11 @@ import (
 	"time"
 )
 
-// ExampleAWSRackLocal shows how the RackAffinityGroupBalancer can be used to
-// pair up consumers with brokers in the same AWS availability zone.  This code
-// assumes that each brokers' rack is configured to be the name of the AZ in
-// which it is running.
-func ExampleAWSRackLocal() {
+// ExampleNewReader_rackAffinity shows how the RackAffinityGroupBalancer can be
+// used to pair up consumers with brokers in the same AWS availability zone.
+// This code assumes that each brokers' rack is configured to be the name of the
+// AZ in which it is running.
+func ExampleNewReader_rackAffinity() {
 	r := NewReader(ReaderConfig{
 		Brokers: []string{"kafka:9092"},
 		GroupID: "my-group",

writer.go

@@ -867,8 +867,11 @@ func (w *Writer) chooseTopic(msg Message) (string, error) {
 type batchQueue struct {
 	queue []*writeBatch
 
-	mutex sync.Mutex
-	cond  sync.Cond
+	// Pointers are used here to make `go vet` happy, and avoid copying mutexes.
+	// It may be better to revert these to non-pointers and avoid the copies in
+	// a different way.
+	mutex *sync.Mutex
+	cond  *sync.Cond
 
 	closed bool
 }
@@ -915,9 +918,11 @@ func (b *batchQueue) Close() {
 func newBatchQueue(initialSize int) batchQueue {
 	bq := batchQueue{
 		queue: make([]*writeBatch, 0, initialSize),
+		mutex: &sync.Mutex{},
+		cond: &sync.Cond{},
 	}
 
-	bq.cond.L = &bq.mutex
+	bq.cond.L = bq.mutex
 
 	return bq
 }