async_producer: clarify ProducerMessage `Timestamp` doc

The `Timestamp` field was introduced in
https://github.com/Shopify/sarama/pull/678 and at this point was only set by
the broker.

Subsequent to this, the changes described in [KIP-32] were implemented,
allowing the `Timestamp` of the message to be set by a producer when the
broker was configured to use `CreateTime`.

This commit updates the doc on the ProducerMessage struct to reflect that
depending on which of the `CreateTime` and `LogAppendTime` modes are active,
the `Timestamp` can be meaningfully set by either the request or the
response.

[KIP-32]: https://cwiki.apache.org/confluence/display/KAFKA/KIP-32+-+Add+timestamps+to+Kafka+message

async_producer.go

@@ -191,10 +191,17 @@ type ProducerMessage struct {
 	// Partition is the partition that the message was sent to. This is only
 	// guaranteed to be defined if the message was successfully delivered.
 	Partition int32
-	// Timestamp is the timestamp assigned to the message by the broker. This
-	// is only guaranteed to be defined if the message was successfully
-	// delivered, RequiredAcks is not NoResponse, and the Kafka broker is at
-	// least version 0.10.0.
+	// Timestamp can vary in behaviour depending on broker configuration, being
+	// in either one of the CreateTime or LogAppendTime modes (default CreateTime),
+	// and requiring version at least 0.10.0.
+	//
+	// When configured to CreateTime, the timestamp is specified by the producer
+	// either by explicitly setting this field, or when the message is added
+	// to a produce set.
+	//
+	// When configured to LogAppendTime, the timestamp assigned to the message
+	// by the broker. This is only guaranteed to be defined if the message was
+	// successfully delivered and RequiredAcks is not NoResponse.
 	Timestamp time.Time
 
 	retries        int