Better documentation, extend test timeout

Makefile

@@ -4,7 +4,7 @@ default: fmt vet errcheck test
 test:
 	echo "" > coverage.txt
 	for d in `go list ./... | grep -v vendor`; do \
-		go test -p 1 -v -timeout 90s -race -coverprofile=profile.out -covermode=atomic $$d || exit 1; \
+		go test -p 1 -v -timeout 180s -race -coverprofile=profile.out -covermode=atomic $$d || exit 1; \
 		if [ -f profile.out ]; then \
 			cat profile.out >> coverage.txt; \
 			rm profile.out; \

balance_strategy.go

@@ -37,7 +37,7 @@ type BalanceStrategy interface {
 // --------------------------------------------------------------------
 
 // BalanceStrategyRange is the default and assigns partitions as ranges to consumer group members.
-// Example with one topic T with six partitions (0..5) and two members (M1, M2) :
+// Example with one topic T with six partitions (0..5) and two members (M1, M2):
 //   M1: {T: [0, 1, 2]}
 //   M2: {T: [3, 4, 5]}
 var BalanceStrategyRange = &balanceStrategy{

consumer_group.go

@@ -416,7 +416,6 @@ func (c *consumerGroup) handleError(err error, topic string, partition int32) {
 // --------------------------------------------------------------------
 
 // ConsumerGroupSession represents a consumer group member session.
-// You MUST call Close() at the end of a session to avoid leaks.
 type ConsumerGroupSession interface {
 	// Claims returns information about the claimed partitions by topic.
 	Claims() map[string][]int32
@@ -685,14 +684,18 @@ type ConsumerGroupHandler interface {
 type ConsumerGroupClaim interface {
 	// Topic returns the consumed topic name.
 	Topic() string
+
 	// Partition returns the consumed partition.
 	Partition() int32
+
 	// InitialOffset returns the initial offset that was used as a starting point for this claim.
 	InitialOffset() int64
+
 	// HighWaterMarkOffset returns the high water mark offset of the partition,
 	// i.e. the offset that will be used for the next message that will be produced.
 	// You can use this to determine how far behind the processing is.
 	HighWaterMarkOffset() int64
+
 	// Messages returns the read channel for the messages that are returned by
 	// the broker. The messages channel will be closed when a new rebalance cycle
 	// is due. You must finish processing and mark offsets within