added doxygen comments again

include/fkYAML/detail/iterator.hpp

@@ -372,11 +372,21 @@ class iterator {
     iterator_holder<value_type> m_iterator_holder {};
 };
 
+/// @brief Get reference to a mapping key node.
+/// @tparam ValueType The iterator value type.
+/// @tparam I The element index.
+/// @param i An iterator object.
+/// @return Reference to a mapping key node.
 template <std::size_t I, typename ValueType, enable_if_t<I == 0, int> = 0>
 inline auto get(const iterator<ValueType>& i) -> decltype(i.key()) {
     return i.key();
 }
 
+/// @brief Get reference to a mapping value node.
+/// @tparam ValueType The iterator value type.
+/// @tparam I The element index
+/// @param i An iterator object.
+/// @return Reference to a mapping value node.
 template <std::size_t I, typename ValueType, enable_if_t<I == 1, int> = 0>
 inline auto get(const iterator<ValueType>& i) -> decltype(i.value()) {
     return i.value();
@@ -393,15 +403,19 @@ namespace std {
 #pragma clang diagnostic ignored "-Wmismatched-tags"
 #endif
 
+/// @brief Parcial pecialization of std::tuple_size for iterator class.
+/// @tparam ValueType The iterator value type.
 template <typename ValueType>
 // NOLINTNEXTLINE(cert-dcl58-cpp)
-struct tuple_size<::fkyaml::detail::iterator<ValueType>> : public integral_constant<size_t, 2> {};
+struct tuple_size<::fkyaml::detail::iterator<ValueType>> : integral_constant<size_t, 2> {};
 
-template <size_t N, typename ValueType>
+/// @brief Parcial specialization of std::tuple_element for iterator class.
+/// @tparam ValueType The iterator value type.
+/// @tparam I The element index.
+template <size_t I, typename ValueType>
 // NOLINTNEXTLINE(cert-dcl58-cpp)
-struct tuple_element<N, ::fkyaml::detail::iterator<ValueType>> {
-public:
-    using type = decltype(get<N>(std::declval<::fkyaml::detail::iterator<ValueType>>()));
+struct tuple_element<I, ::fkyaml::detail::iterator<ValueType>> {
+    using type = decltype(get<I>(std::declval<::fkyaml::detail::iterator<ValueType>>()));
 };
 
 #ifdef __clang__

include/fkYAML/detail/map_range_proxy.hpp

@@ -14,108 +14,174 @@
 
 FK_YAML_DETAIL_NAMESPACE_BEGIN
 
+/// @brief A helper iterator class which wraps a mapping iterator object.
+/// @tparam Iterator The base iterator type.
 template <typename Iterator>
 class map_iterator_proxy {
 public:
+    /// @brief The type of the pointed-to elements by base iterators.
     using value_type = Iterator;
+
+    /// @brief The type to represent difference between the pointed-to elements by base iterators.
     using difference_type = std::ptrdiff_t;
+
+    /// @brief The type of the pointed-to element references by base iterators.
     using reference = value_type&;
+
+    /// @brief The type of the pointed-to element pointers by base iterators.
     using pointer = value_type*;
+
+    /// @brief The iterator category.
     using iterator_category = std::forward_iterator_tag;
 
+    /// @brief Constructs a map_iterator_proxy object.
     map_iterator_proxy() = default;
 
+    /// @brief Constructs a map_iterator_proxy object with an Iterator object.
+    /// @param i A base iterator object.
     map_iterator_proxy(const Iterator& i) noexcept
         : m_base_iterator(i) {
     }
 
+    /// @brief Copy constructs a map_iterator_proxy object.
     map_iterator_proxy(const map_iterator_proxy&) = default;
+
+    /// @brief Copy assigns a map_iterator_proxy object.
     map_iterator_proxy& operator=(const map_iterator_proxy&) = default;
+
+    /// @brief Move constructs a map_iterator_proxy object.
     map_iterator_proxy(map_iterator_proxy&&) = default;
+
+    /// @biref Move assigns a map_iterator_proxy object.
     map_iterator_proxy& operator=(map_iterator_proxy&&) = default;
 
+    /// @brief Destructs a map_iterator_proxy object.
     ~map_iterator_proxy() = default;
 
+    /// @brief Get reference to the base iterator object.
+    /// @return Reference to the base iterator object.
     reference operator*() noexcept {
         return m_base_iterator;
     }
 
+    /// @brief Get pointer to the base iterator object.
+    /// @return Pointer to the base iterator object.
     pointer operator->() noexcept {
         return &m_base_iterator;
     }
 
+    /// @brief Pre-increments the base iterator object.
+    /// @return Reference to this map_iterator_proxy object.
     map_iterator_proxy& operator++() noexcept {
         ++m_base_iterator;
         return *this;
     }
 
+    /// @brief Post-increments the base iterator object.
+    /// @return A map_iterator_proxy object with its base iterator incremented.
     map_iterator_proxy operator++(int) & noexcept {
         auto result = *this;
         ++(*this);
         return result;
     }
 
+    /// @brief Check equality between map_iterator_proxy objects.
+    /// @param rhs A map_iterator_proxy object to compare with.
+    /// @return true if this map_iterator_proxy object is equal to `rhs`, false otherwise.
     bool operator==(const map_iterator_proxy& rhs) const noexcept {
         return m_base_iterator == rhs.m_base_iterator;
     }
 
+    /// @brief Check inequality between map_iterator_proxy objects.
+    /// @param rhs A map_iterator_proxy object to compare with.
+    /// @return true if this map_iterator_proxy object is not equal to `rhs`, false otherwise.
     bool operator!=(const map_iterator_proxy& rhs) const noexcept {
         return m_base_iterator != rhs.m_base_iterator;
     }
 
+    /// @brief Get the mapping key node pointed by the base iterator.
+    /// @return Reference to the mapping key node.
     typename Iterator::reference key() const {
         return m_base_iterator.key();
     }
 
+    /// @brief Get the mapping value node pointed by the base iterator.
+    /// @return Reference to the mapping value node.
     typename Iterator::reference value() const noexcept {
         return m_base_iterator.value();
     }
 
 private:
+    /// The base iterator object.
     Iterator m_base_iterator {};
 };
 
+/// @brief A helper struct which allows accessing node iterator member functions in range-based for loops.
+/// @tparam BasicNodeType A basic_node template instance type.
 template <typename BasicNodeType>
 class map_range_proxy {
     static_assert(
         is_basic_node<remove_cv_t<BasicNodeType>>::value,
         "map_range_proxy only accepts a basic_node type as its template parameter.");
 
 public:
+    /// @brief The type of non-const iterators.
     using iterator = map_iterator_proxy<typename std::conditional<
         std::is_const<BasicNodeType>::value, typename BasicNodeType::const_iterator,
         typename BasicNodeType::iterator>::type>;
 
+    /// @brief The type of const iterators.
     using const_iterator = map_iterator_proxy<typename BasicNodeType::const_iterator>;
 
+    /// @brief Constructs a map_range_proxy object with a BasicNodeType object.
+    /// @param map A mapping node object.
     map_range_proxy(BasicNodeType& map) noexcept
         : mp_map(&map) {
     }
 
+    /// @brief Copy constructs a map_range_proxy object.
     map_range_proxy(const map_range_proxy&) = default;
+
+    /// @brief Copy assigns a map_range_proxy object.
+    /// @return Reference to this map_range_proxy object.
     map_range_proxy& operator=(const map_range_proxy&) = default;
+
+    /// @brief Move constructs a map_range_proxy object.
     map_range_proxy(map_range_proxy&&) = default;
+
+    /// @brief Move assigns a map_range_proxy object.
+    /// @return Reference to this map_range_proxy object.
     map_range_proxy& operator=(map_range_proxy&&) = default;
 
+    /// @brief Destructs a map_range_proxy object.
     ~map_range_proxy() = default;
 
+    /// @brief Get an iterator to the first element.
+    /// @return An iterator to the first element.
     iterator begin() noexcept {
         return {mp_map->begin()};
     }
 
+    /// @brief Get a const iterator to the first element.
+    /// @return A const iterator to the first element.
     const_iterator begin() const noexcept {
         return {mp_map->cbegin()};
     }
 
+    /// @brief Get an iterator to the past-the-last element.
+    /// @return An iterator to the past-the-last element.
     iterator end() noexcept {
         return {mp_map->end()};
     }
 
+    /// @brief Get a const iterator to the past-the-last element.
+    /// @return A const iterator to the past-the-last element.
     const_iterator end() const noexcept {
         return {mp_map->cend()};
     }
 
 private:
+    /// Pointer to the mapping node object. (non-null)
     BasicNodeType* mp_map {nullptr};
 };
 

include/fkYAML/detail/reverse_iterator.hpp

@@ -64,11 +64,18 @@ class reverse_iterator {
         : m_current(i) {
     }
 
+    /// @brief Copy constructs a reverse_iterator object with a compatible reverse_iterator object.
+    /// @tparam U A compatible iterator type with Iterator.
+    /// @param other A compatible reverse_iterator object.
     template <typename U, enable_if_t<negation<std::is_same<U, Iterator>>::value, int> = 0>
     reverse_iterator(const reverse_iterator<U>& other) noexcept
         : m_current(other.base()) {
     }
 
+    /// @brief Copy assigns a reverse_iterator object with a compatible reverse_iterator object.
+    /// @tparam U A compatible iterator type with Iterator.
+    /// @param other A compatible reverse_iterator object.
+    /// @return Reference to this reverse_iterator object.
     template <typename U, enable_if_t<negation<std::is_same<U, Iterator>>::value, int> = 0>
     reverse_iterator& operator=(const reverse_iterator<U>& other) noexcept {
         m_current = other.base();
@@ -172,34 +179,71 @@ class reverse_iterator {
     }
 
 private:
+    ///
     Iterator m_current;
 };
 
+/// @brief Check equality between reverse_iterator objects.
+/// @tparam IteratorL Base iterator type for `lhs`.
+/// @tparam IteratorR Base iterator type for `rhs`.
+/// @param lhs A reverse_iterator object.
+/// @param rhs A reverse_iterator object.
+/// @return true if the two reverse_iterator objects are equal, false otherwise.
 template <typename IteratorL, typename IteratorR>
 inline bool operator==(const reverse_iterator<IteratorL>& lhs, const reverse_iterator<IteratorR>& rhs) {
     return lhs.base() == rhs.base();
 }
 
+/// @brief Check inequality between reverse_iterator objects.
+/// @tparam IteratorL Base iterator type for `lhs`.
+/// @tparam IteratorR Base iterator type for `rhs`.
+/// @param lhs A reverse_iterator object.
+/// @param rhs A reverse_iterator object.
+/// @return true if the two reverse_iterator objects are not equal, false otherwise.
 template <typename IteratorL, typename IteratorR>
 inline bool operator!=(const reverse_iterator<IteratorL>& lhs, const reverse_iterator<IteratorR>& rhs) {
     return lhs.base() != rhs.base();
 }
 
+/// @brief Check if `lhs` is less than `rhs`.
+/// @tparam IteratorL Base iterator type for `lhs`.
+/// @tparam IteratorR Base iterator type for `rhs`.
+/// @param lhs A reverse_iterator object.
+/// @param rhs A reverse_iterator object.
+/// @return true if `lhs` is less than `rhs`, false otherwise.
 template <typename IteratorL, typename IteratorR>
 inline bool operator<(const reverse_iterator<IteratorL>& lhs, const reverse_iterator<IteratorR>& rhs) {
     return lhs.base() > rhs.base();
 }
 
+/// @brief Check if `lhs` is less than or equal to `rhs`.
+/// @tparam IteratorL Base iterator type for `lhs`.
+/// @tparam IteratorR Base iterator type for `rhs`.
+/// @param lhs A reverse_iterator object.
+/// @param rhs A reverse_iterator object.
+/// @return true if `lhs` is less than or equal to `rhs`, false otherwise.
 template <typename IteratorL, typename IteratorR>
 inline bool operator<=(const reverse_iterator<IteratorL>& lhs, const reverse_iterator<IteratorR>& rhs) {
     return lhs.base() >= rhs.base();
 }
 
+/// @brief Check if `lhs` is greater than `rhs`.
+/// @tparam IteratorL Base iterator type for `lhs`.
+/// @tparam IteratorR Base iterator type for `rhs`.
+/// @param lhs A reverse_iterator object.
+/// @param rhs A reverse_iterator object.
+/// @return true if `lhs` is greater than `rhs`, false otherwise.
 template <typename IteratorL, typename IteratorR>
 inline bool operator>(const reverse_iterator<IteratorL>& lhs, const reverse_iterator<IteratorR>& rhs) {
     return lhs.base() < rhs.base();
 }
 
+/// @brief Check if `lhs` is greater than or equal to `rhs`.
+/// @tparam IteratorL Base iterator type for `lhs`.
+/// @tparam IteratorR Base iterator type for `rhs`.
+/// @param lhs A reverse_iterator object.
+/// @param rhs A reverse_iterator object.
+/// @return true if `lhs` is greater than or equal to `rhs`, false otherwise.
 template <typename IteratorL, typename IteratorR>
 inline bool operator>=(const reverse_iterator<IteratorL>& lhs, const reverse_iterator<IteratorR>& rhs) {
     return lhs.base() <= rhs.base();