Upgrade to protozero 1.7.1 (#5)

* Upgrade to protozero 1.7.1

* Bump version number

protozero/pbf_message.hpp

@@ -16,10 +16,10 @@ documentation.
  * @brief Contains the pbf_message template class.
  */
 
-#include <type_traits>
+#include "pbf_reader.hpp"
+#include "types.hpp"
 
-#include <protozero/pbf_reader.hpp>
-#include <protozero/types.hpp>
+#include <type_traits>
 
 namespace protozero {
 
@@ -35,7 +35,7 @@ namespace protozero {
  *
  *    std::string buffer;
  *    // fill buffer...
- *    pbf_message<Message> message(buffer.data(), buffer.size());
+ *    pbf_message<Message> message{buffer.data(), buffer.size()};
  * @endcode
  *
  * Sub-messages are created using get_message():
@@ -45,7 +45,7 @@ namespace protozero {
  *       ...
  *    };
  *
- *    pbf_message<Message> message(...);
+ *    pbf_message<Message> message{...};
  *    message.next();
  *    pbf_message<SubMessage> submessage = message.get_message();
  * @endcode
@@ -64,29 +64,115 @@ namespace protozero {
 template <typename T>
 class pbf_message : public pbf_reader {
 
-    static_assert(std::is_same<pbf_tag_type, typename std::underlying_type<T>::type>::value, "T must be enum with underlying type protozero::pbf_tag_type");
+    static_assert(std::is_same<pbf_tag_type, typename std::underlying_type<T>::type>::value,
+                  "T must be enum with underlying type protozero::pbf_tag_type");
 
 public:
 
+    /// The type of messages this class will read.
     using enum_type = T;
 
+    /**
+     * Construct a pbf_message. All arguments are forwarded to the pbf_reader
+     * parent class.
+     */
     template <typename... Args>
-    pbf_message(Args&&... args) noexcept :
-        pbf_reader(std::forward<Args>(args)...) {
+    pbf_message(Args&&... args) noexcept : // NOLINT(google-explicit-constructor, hicpp-explicit-conversions)
+        pbf_reader{std::forward<Args>(args)...} {
     }
 
+    /**
+     * Set next field in the message as the current field. This is usually
+     * called in a while loop:
+     *
+     * @code
+     *    pbf_message<...> message(...);
+     *    while (message.next()) {
+     *        // handle field
+     *    }
+     * @endcode
+     *
+     * @returns `true` if there is a next field, `false` if not.
+     * @pre There must be no current field.
+     * @post If it returns `true` there is a current field now.
+     */
     bool next() {
         return pbf_reader::next();
     }
 
+    /**
+     * Set next field with given tag in the message as the current field.
+     * Fields with other tags are skipped. This is usually called in a while
+     * loop for repeated fields:
+     *
+     * @code
+     *    pbf_message<Example1> message{...};
+     *    while (message.next(Example1::repeated_fixed64_r)) {
+     *        // handle field
+     *    }
+     * @endcode
+     *
+     * or you can call it just once to get the one field with this tag:
+     *
+     * @code
+     *    pbf_message<Example1> message{...};
+     *    if (message.next(Example1::required_uint32_x)) {
+     *        // handle field
+     *    }
+     * @endcode
+     *
+     * Note that this will not check the wire type. The two-argument version
+     * of this function will also check the wire type.
+     *
+     * @returns `true` if there is a next field with this tag.
+     * @pre There must be no current field.
+     * @post If it returns `true` there is a current field now with the given tag.
+     */
     bool next(T next_tag) {
         return pbf_reader::next(pbf_tag_type(next_tag));
     }
 
+    /**
+     * Set next field with given tag and wire type in the message as the
+     * current field. Fields with other tags are skipped. This is usually
+     * called in a while loop for repeated fields:
+     *
+     * @code
+     *    pbf_message<Example1> message{...};
+     *    while (message.next(Example1::repeated_fixed64_r, pbf_wire_type::varint)) {
+     *        // handle field
+     *    }
+     * @endcode
+     *
+     * or you can call it just once to get the one field with this tag:
+     *
+     * @code
+     *    pbf_message<Example1> message{...};
+     *    if (message.next(Example1::required_uint32_x, pbf_wire_type::varint)) {
+     *        // handle field
+     *    }
+     * @endcode
+     *
+     * Note that this will also check the wire type. The one-argument version
+     * of this function will not check the wire type.
+     *
+     * @returns `true` if there is a next field with this tag.
+     * @pre There must be no current field.
+     * @post If it returns `true` there is a current field now with the given tag.
+     */
     bool next(T next_tag, pbf_wire_type type) {
         return pbf_reader::next(pbf_tag_type(next_tag), type);
     }
 
+    /**
+     * The tag of the current field. The tag is the enum value for the field
+     * number from the description in the .proto file.
+     *
+     * Call next() before calling this function to set the current field.
+     *
+     * @returns tag of the current field.
+     * @pre There must be a current field (ie. next() must have returned `true`).
+     */
     T tag() const noexcept {
         return T(pbf_reader::tag());
     }