Minor documentation improvements

Author: mfontanini

include/cppkafka/consumer.h

@@ -79,17 +79,17 @@ class TopicConfiguration;
  * consumer.subscribe({ "my_topic" });
  * while (true) {
  *     // Poll. This will optionally return a message. It's necessary to check if it's a valid
- *     // one before using it or bad things will happen
+ *     // one before using it
  *     Message msg = consumer.poll(); 
  *     if (msg) {
- *         // It's a valid message!
  *         if (!msg.get_error()) {
  *             // It's an actual message. Get the payload and print it to stdout
  *             cout << msg.get_payload().as_string() << endl;
  *         }
- *         else {
- *             // Is it an error notification
- *             // ...
+ *         else if (!msg.is_eof()) {
+ *             // Is it an error notification, handle it.
+ *             // This is explicitly skipping EOF notifications as they're not actually errors,
+ *             // but that's how rdkafka provides them
  *         }
  *     }
  * }

include/cppkafka/message.h

@@ -48,7 +48,7 @@ class MessageTimestamp;
  *
  * This is a non copyable, movable class that wraps a rd_kafka_message_t*.
  *
- * Messages can be empty (contain a null rd_kafka_message_t*). Therefore, users should check
+ * Messages can be empty (contain a null rd_kafka_message_t*). Therefore, users must check
  * that the message isn't empty by using the operator bool() before using them. This is especially
  * necessary when calling Consumer::poll() as any poll operation that returns a null pointer will
  * return an empty message.
@@ -151,6 +151,9 @@ class CPPKAFKA_API Message {
     Buffer key_;
 };
 
+/**
+ * Represents a message's timestamp
+ */
 class CPPKAFKA_API MessageTimestamp {
 public:
     /**

include/cppkafka/producer.h

@@ -65,7 +65,7 @@ class TopicConfiguration;
  * Producer producer(config);
  *
  * // Create some key and payload
- * string key = "creative_key_name";
+ * string key = "some key";
  * string payload = "some payload";
  *
  * // Write a message into an unassigned partition
@@ -78,6 +78,9 @@ class TopicConfiguration;
  */
 class CPPKAFKA_API Producer : public KafkaHandleBase {
 public:
+    /**
+     * The policy to use for the payload. The default policy is COPY_PAYLOAD
+     */
     enum PayloadPolicy {
         COPY_PAYLOAD = RD_KAFKA_MSG_F_COPY, ///< Means RD_KAFKA_MSG_F_COPY
         FREE_PAYLOAD = RD_KAFKA_MSG_F_FREE  ///< Means RD_KAFKA_MSG_F_FREE