Switch to doxygen to generate documentation

c++/itertools/enumerate.hpp

@@ -34,14 +34,15 @@ namespace itertools {
   namespace detail {
 
     /**
+     * @ingroup range_iterators
      * @brief Iterator for a detail::enumerated range.
-     * 
+     *
      * @details It stores an iterator of the original range and an index. Incrementing advances the iterator
-     * and the index by 1. Dereferencing returns a std::pair consisting of the current index and the current 
+     * and the index by 1. Dereferencing returns a std::pair consisting of the current index and the current
      * dereferenced value of the original iterator.
-     * 
+     *
      * See itertools::enumerate(R &&) for more details.
-     * 
+     *
      * @tparam Iter Iterator type.
      */
     template <typename Iter> struct enum_iter : iterator_facade<enum_iter<Iter>, std::pair<long, typename std::iterator_traits<Iter>::value_type>> {
@@ -68,15 +69,15 @@ namespace itertools {
 
       /**
        * @brief Equal-to operator for two detail::enum_iter objects.
-       * 
+       *
        * @param other detail::enum_iter to compare with.
        * @return True, if the original iterators are equal.
        */
       [[nodiscard]] bool operator==(enum_iter const &other) const { return it == other.it; }
 
       /**
        * @brief Equal-to operator for a detail::enum_iter and an itertools::sentinel_t.
-       * 
+       *
        * @tparam SentinelIter Iterator type of the sentinel.
        * @param s itertools::sentinel_t to compare with.
        * @return True, if the original iterator is equal to the iterator stored in the sentinel.
@@ -91,10 +92,11 @@ namespace itertools {
     };
 
     /**
+     * @ingroup adapted_ranges
      * @brief Represents an enumerated range.
-     * 
+     *
      * @details See itertools::enumerate(R &&) for more details.
-     * 
+     *
      * @tparam R Range type.
      */
     template <typename R> struct enumerated {
@@ -138,28 +140,29 @@ namespace itertools {
   } // namespace detail
 
   /**
+   * @ingroup range_adapting_functions
    * @brief Lazy-enumerate a given range (similar to Python's enumerate).
-   * 
-   * @details Each element in the original range is assigned an index, starting from zero. This function 
+   *
+   * @details Each element in the original range is assigned an index, starting from zero. This function
    * returns an iterable lazy object (a detail::enumerated range), which iterates over tuples consisting of the
    * index and the value of the dereferenced iterator of the original range:
-   * 
+   *
    * @code{.cpp}
    * std::vector<char> vec { 'a', 'b', 'c' };
-   * 
+   *
    * for (auto [idx, val] : enumerate(vec)) {
    *   std::cout << "(" << idx << ", " << val << ")\n";
    * }
    * @endcode
-   * 
+   *
    * Output:
-   * 
+   *
    * ```
    * (0, a)
    * (1, b)
    * (2, c)
    * ```
-   * 
+   *
    * See also <a href="https://en.cppreference.com/w/cpp/ranges/enumerate_view">std::ranges::views::enumerate</a>.
    *
    * @tparam R Range type.

c++/itertools/iterator_facade.hpp

@@ -27,28 +27,31 @@
 
 namespace itertools {
 
+  /// @cond
   // Forward declaration.
   template <typename Iter, typename Value, typename Tag = std::forward_iterator_tag, typename Reference = Value &,
             typename Difference = std::ptrdiff_t>
   struct iterator_facade;
+  /// @endcond
 
   /**
+   * @ingroup utilities
    * @brief CRTP base class for various iterator types in itertools.
-   * 
-   * @details All iterator types defined in itertools are derived from this class. It uses the 
+   *
+   * @details All iterator types defined in itertools are derived from this class. It uses the
    * <a href="https://en.cppreference.com/w/cpp/iterator/forward_iterator">forward iterator</a>
    * category. Derived classes are required to implement the following member functions:
-   * 
+   *
    * @code{.cpp}
    * // used by operator++() and operator++(int)
    * void increment();
-   * 
+   *
    * // used by operator*() and operator->()
    * value_type [const] [&] dereference() [const];
    * @endcode
-   * 
+   *
    * The `[..]` are optional and depend on the actual iterator type.
-   * 
+   *
    * @tparam Iter Derived iterator type.
    * @tparam Value Value type of the iterator.
    * @tparam Reference Reference type of the iterator.
@@ -57,10 +60,10 @@ namespace itertools {
   template <typename Iter, typename Value, typename Reference, typename Difference>
   struct iterator_facade<Iter, Value, std::forward_iterator_tag, Reference, Difference> {
     private:
-    /// Get a reference to the derived iterator.
+    // Get a reference to the derived iterator.
     [[nodiscard]] Iter &self() { return static_cast<Iter &>(*this); }
 
-    /// Get a const reference to the derived iterator.
+    // Get a const reference to the derived iterator.
     [[nodiscard]] Iter const &self() const { return static_cast<const Iter &>(*this); }
 
     public:

c++/itertools/omp_chunk.hpp

@@ -14,6 +14,11 @@
 //
 // Authors: Olivier Parcollet, Nils Wentzell
 
+/**
+ * @file
+ * @brief Provides utilities to distribute a range across OMP threads.
+ */
+
 #pragma once
 
 #include "./itertools.hpp"
@@ -23,6 +28,7 @@
 namespace itertools {
 
   /**
+   * @ingroup utilities
    * @brief Distribute a range as evenly as possible across all OMP threads.
    *
    * @details See chunk_range(std::ptrdiff_t, std::ptrdiff_t, long, long) and slice(R &&, std::ptrdiff_t, std::ptrdiff_t) for more details.

c++/itertools/product.hpp

@@ -32,28 +32,32 @@
 
 namespace itertools {
 
+  /// @cond
   // Forward declarations.
   namespace detail {
     template <typename... Rs> struct multiplied;
   }
   template <typename... Rs> detail::multiplied<Rs...> product(Rs &&...);
+  /// @endcond
 
   namespace detail {
 
     /**
+     * @ingroup range_iterators
      * @brief Iterator for a detail::multiplied (cartesian product) range.
-     * 
+     *
      * @details It stores three tuples of iterators of the original ranges:
      * - `its_begin` contains the begin iterators of all ranges
      * - `its_end` contains the end iterators of all ranges
      * - `its` contains the current iterators of all ranges
-     * 
-     * Incrementing increments one iterator at a time in row-major order, i.e. if one iterator is equal to its
-     * end iterator, it is reset to its begin iterator and the previous iterator is incremented. Dereferencing 
-     * returns a tuple containing the results of dereferencing each iterator.
-     * 
+     *
+     * Incrementing is done from right to left, i.e. the iterator of the last range is incremented first.
+     * Once an iterator reaches the end of its range, it is reset to the beginning and the iterator of the
+     * previous range is incremented once.
+     * Dereferencing returns a tuple containing the results of dereferencing each iterator.
+     *
      * See itertools::product(Rs &&...rgs) for more details.
-     * 
+     *
      * @tparam EndIters Tuple type containing the end iterators of all ranges.
      * @tparam Iters Iterator types.
      */
@@ -76,17 +80,14 @@ namespace itertools {
 
       /**
        * @brief Construct a product iterator from given begin iterators and end iterators.
-       * 
+       *
        * @param its_begin Tuple containing begin iterators of the original ranges.
        * @param its_end Tuple containing end iterators of the original ranges.
        */
       prod_iter(std::tuple<Iters...> its_begin, EndIters its_end) : its_begin(std::move(its_begin)), its_end(std::move(its_end)) {}
 
       private:
-      /**
-       * @brief Helper function which recursively increments the current iterators in row-major order.
-       * @tparam N Iterator index to increment.
-       */
+      // Helper function to recursively increment the current iterators.
       template <int N> void _increment() {
         // increment Nth iterator
         ++std::get<N>(its);
@@ -101,34 +102,30 @@ namespace itertools {
       }
 
       public:
-      /// Increment the iterator by incrementing the current iterators in row-major order.
+      /// Increment the iterator by incrementing the current iterators starting with the iterator of the last range.
       void increment() { _increment<Rank - 1>(); }
 
       /**
        * @brief Equal-to operator for two detail::prod_iter objects.
-       * 
+       *
        * @param other detail::prod_iter to compare with.
        * @return True, if all original iterators are equal.
        */
       [[nodiscard]] bool operator==(prod_iter const &other) const { return its == other.its; }
 
       /**
        * @brief Equal-to operator for a detail::prod_iter and an itertools::sentinel_t.
-       * 
-       * @details Since we traverse the cartesian product in row-major order, we reach the end of the product range,
-       * when the first iterator, i.e. `std::get<0>(its)`, is at its end.
-       * 
+       *
+       * @details We reach the end of the product range, when the first iterator, i.e. `std::get<0>(its)`, is at its end.
+       *
        * @tparam SentinelIter Iterator type of the sentinel.
        * @param s itertools::sentinel_t to compare with.
        * @return True, if the first iterator, i.e. `std::get<0>(its)`, is equal to the iterator of the sentinel.
        */
       template <typename SentinelIter> [[nodiscard]] bool operator==(sentinel_t<SentinelIter> const &s) const { return (s.it == std::get<0>(its)); }
 
       private:
-      /**
-       * @brief Helper function to dereference all original iterators.
-       * @return Tuple containing the dereferenced values of all original iterators.
-       */
+      // Helper function to dereference all original iterators.
       template <size_t... Is> [[gnu::always_inline]] [[nodiscard]] auto tuple_map_impl(std::index_sequence<Is...>) const {
         return std::tuple<decltype(*std::get<Is>(its))...>(*std::get<Is>(its)...);
       }
@@ -142,10 +139,11 @@ namespace itertools {
     };
 
     /**
+     * @ingroup adapted_ranges
      * @brief Represents a cartesian product of ranges.
-     * 
+     *
      * @details See itertools::product(Rs &&...rgs) for more details.
-     * 
+     *
      * @tparam Rs Range types.
      */
     template <typename... Rs> struct multiplied {
@@ -160,7 +158,7 @@ namespace itertools {
 
       /**
        * @brief Constructs a cartesian product (multiplied) range from the given ranges.
-       * 
+       *
        * @tparam Us Range types.
        * @param rgs Ranges to be multiplied.
        */
@@ -170,12 +168,12 @@ namespace itertools {
       [[nodiscard]] bool operator==(multiplied const &) const = default;
 
       private:
-      /// Helper function to create a detail::prod_iter representing the beginning of the product range.
+      // Helper function to create a detail::prod_iter representing the beginning of the product range.
       template <size_t... Is> [[gnu::always_inline]] auto _begin(std::index_sequence<Is...>) {
         return iterator{std::make_tuple(std::begin(std::get<Is>(tu))...), std::make_tuple(std::end(std::get<Is>(tu))...)};
       }
 
-      /// Const version of _begin(std::index_sequence<Is...>).
+      // Const version of _begin(std::index_sequence<Is...>).
       template <size_t... Is> [[gnu::always_inline]] auto _cbegin(std::index_sequence<Is...>) const {
         return const_iterator{std::make_tuple(std::cbegin(std::get<Is>(tu))...), std::make_tuple(std::cend(std::get<Is>(tu))...)};
       }
@@ -206,40 +204,42 @@ namespace itertools {
       [[nodiscard]] auto end() const noexcept { return cend(); }
     };
 
+    /// @cond
     // Class template argument deduction guide.
     template <typename... Rs> multiplied(Rs &&...) -> multiplied<std::decay_t<Rs>...>;
 
-    /**
-     * @brief Helper function to create a product range from a container of ranges.
-     * 
-     * @tparam C Container type.
-     * @param cont Container of ranges.
-     * @return Product range from the ranges in the container.
-     */
+    // Helper function to create a product range from a container of ranges.
     template <typename C, size_t... Is> [[gnu::always_inline]] [[nodiscard]] auto make_product_impl(C &cont, std::index_sequence<Is...>) {
       return product(cont[Is]...);
     }
+    /// @endcond
 
   } // namespace detail
 
+  /**
+   * @addtogroup range_adapting_functions
+   * @{
+   */
+
   /**
    * @brief Lazy-multiply a given number of ranges by forming their cartesian product.
    *
-   * @details An arbitrary number of ranges are multiplied together into a cartesian product range. They are traversed in a row-major
-   * order, i.e. the last range is the fastest dimension. The number of elements in a product range is equal to the product of 
-   * the sizes of the given ranges. This function returns an iterable lazy object, which can be used in range-based for loops:
-   * 
+   * @details An arbitrary number of ranges are multiplied together into a cartesian product range.
+   * They are traversed such that the last range is traversed the fastest (see the example below).
+   * The number of elements in a product range is equal to the product of the sizes of the given ranges.
+   * This function returns an iterable lazy object, which can be used in range-based for loops:
+   *
    * @code{.cpp}
    * std::vector<int> v1 { 1, 2, 3 };
    * std::vector<char> v2 { 'a', 'b' };
-   * 
+   *
    * for (auto [i, c] : product(v1, v2)) {
    *   std::cout << "(" << i << ", " << c << ")\n";
    * }
    * @endcode
-   * 
+   *
    * Output:
-   * 
+   *
    * ```
    * (1, a)
    * (1, b)
@@ -248,7 +248,7 @@ namespace itertools {
    * (3, a)
    * (3, b)
    * ```
-   * 
+   *
    * See also <a href="https://en.cppreference.com/w/cpp/ranges/cartesian_product_view">std::ranges::views::cartesian_product</a>.
    *
    * @tparam Rs Range types.
@@ -259,7 +259,7 @@ namespace itertools {
 
   /**
    * @brief Create a cartesian product range from an array of ranges.
-   * 
+   *
    * @tparam R Range type.
    * @tparam N Number of ranges.
    * @param arr Array of ranges.
@@ -274,6 +274,8 @@ namespace itertools {
     return detail::make_product_impl(arr, std::make_index_sequence<N>{});
   }
 
+  /** @} */
+
 } // namespace itertools
 
 #endif // _ITERTOOLS_PRODUCT_HPP