document CommitOffsets behavior (#785)

Author: Achille

README.md

@@ -328,6 +328,13 @@ for {
 }
 ```
 
+When committing messages in consumer groups, the message with the highest offset
+for a given topic/partition determines the value of the committed offset for
+that partition. For example, if messages at offset 1, 2, and 3 of a single
+partition were retrieved by call to `FetchMessage`, calling `CommitMessages`
+with message offset 3 will also result in committing the messages at offsets 1
+and 2 for that partition.
+
 ### Managing Commits
 
 By default, CommitMessages will synchronously commit offsets to Kafka.  For

reader.go

@@ -847,6 +847,15 @@ func (r *Reader) FetchMessage(ctx context.Context) (Message, error) {
 // CommitMessages commits the list of messages passed as argument. The program
 // may pass a context to asynchronously cancel the commit operation when it was
 // configured to be blocking.
+//
+// Because kafka consumer groups track a single offset per partition, the
+// highest message offset passed to CommitMessages will cause all previous
+// messages to be committed. Applications need to account for these Kafka
+// limitations when committing messages, and maintain message ordering if they
+// need strong delivery guarantees. This property makes it valid to pass only
+// the last message seen to CommitMessages in order to move the offset of the
+// topic/partition it belonged to forward, effectively committing all previous
+// messages in the partition.
 func (r *Reader) CommitMessages(ctx context.Context, msgs ...Message) error {
 	if !r.useConsumerGroup() {
 		return errOnlyAvailableWithGroup