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.

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,31 @@
 
 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 
+     * 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.
-     * 
+     *
      * See itertools::product(Rs &&...rgs) for more details.
-     * 
+     *
      * @tparam EndIters Tuple type containing the end iterators of all ranges.
      * @tparam Iters Iterator types.
      */
@@ -76,7 +79,7 @@ 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.
        */
@@ -106,18 +109,18 @@ namespace itertools {
 
       /**
        * @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.
-       * 
+       *
        * @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.
@@ -142,10 +145,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 +164,7 @@ namespace itertools {
 
       /**
        * @brief Constructs a cartesian product (multiplied) range from the given ranges.
-       * 
+       *
        * @tparam Us Range types.
        * @param rgs Ranges to be multiplied.
        */
@@ -206,40 +210,47 @@ 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.
      */
     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 
+   * 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:
-   * 
+   *
    * @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 +259,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 +270,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 +285,8 @@ namespace itertools {
     return detail::make_product_impl(arr, std::make_index_sequence<N>{});
   }
 
+  /** @} */
+
 } // namespace itertools
 
 #endif // _ITERTOOLS_PRODUCT_HPP