Add more documentation comments by iFlow CLI

Author: luk036

README.md

@@ -22,7 +22,7 @@
 - Reproducible dependency management via [CPM.cmake](https://github.com/TheLartians/CPM.cmake)
 - Installable target with automatic versioning information and header generation via [PackageProject.cmake](https://github.com/TheLartians/PackageProject.cmake)
 - Automatic [documentation](https://thelartians.github.io/ModernCppStarter) and deployment with [Doxygen](https://www.doxygen.nl) and [GitHub Pages](https://pages.github.com)
-- Support for [sanitizer tools, and more](#additional-tools)
+- Support for sanitizer tools and more
 
 ## Usage
 
@@ -41,7 +41,7 @@ Eventually, you can remove any unused files, such as the standalone directory or
 Feel free to replace the License with one suited for your project.
 
 To cleanly separate the library and subproject code, the outer `CMakeList.txt` only defines the library itself while the tests and other subprojects are self-contained in their own directories.
-During development it is usually convenient to [build all subprojects at once](#build-everything-at-once).
+During development it is usually convenient to build all subprojects at once.
 
 ### Build and run the standalone target
 

documentation/Doxyfile

@@ -26,6 +26,4 @@ GENERATE_LATEX = NO
 XML_PROGRAMLISTING = NO
 CREATE_SUBDIRS = NO
 
-# Include all directories, files and namespaces in the documentation
-# Disable to include only explicitly documented objects
-M_SHOW_UNDOCUMENTED = YES
+

documentation/conf.py

@@ -1,3 +1,24 @@
+import warnings
+import logging
+
+# Suppress Python deprecation warnings about testing element truth values
+warnings.filterwarnings("ignore", category=DeprecationWarning, message=".*Testing an element's truth value.*")
+
+# Suppress warnings about external images not found in XML output
+warnings.filterwarnings("ignore", message=".*was not found in XML_OUTPUT", category=RuntimeWarning)
+warnings.filterwarnings("ignore", message=".*was not found in XML_OUTPUT", category=UserWarning)
+
+# Suppress the specific logging messages about external images in m.css
+class ImageNotFoundFilter(logging.Filter):
+    def filter(self, record):
+        # Suppress specific image not found messages
+        if "was not found in XML_OUTPUT" in record.getMessage():
+            return False
+        return True
+
+# Apply the filter to the root logger
+logging.getLogger().addFilter(ImageNotFoundFilter())
+
 DOXYFILE = 'Doxyfile'
 
 LINKS_NAVBAR1 = [
@@ -10,10 +31,10 @@
 
 # LINKS_NAVBAR1 = [
 #     (None, 'pages', [(None, 'about')]),
-#     (None, 'namespaces', [(None, 'namespacepy2cpp')]),
+#     (None, 'namespaces', [(None, 'namespacexnetwork')]),
 # ]
 #
 # LINKS_NAVBAR2 = [
-#     (None, 'annotated', [(None, 'classpy2cpp_1_1_py2cpp')]),
-#     (None, 'files', [(None, 'py2cpp_8h')]),
+#     (None, 'annotated', [(None, 'classxnetwork_1_1_xnetwork')]),
+#     (None, 'files', [(None, 'xnetwork_8h')]),
 # ]

include/py2cpp/dict.hpp

@@ -11,18 +11,49 @@
 namespace py {
 
     /**
-     * @brief
+     * @brief Iterator adapter for accessing keys in map-like containers
+     *
+     * Provides an iterator that dereferences to the key component of
+     * key-value pairs in map-like containers.
      *
-     * @tparam Iter
+     * @tparam Iter The underlying iterator type for key-value pairs
      */
     template <typename Iter> struct key_iterator : Iter {
+        /**
+         * @brief Construct a key iterator from an underlying iterator
+         *
+         * @param[in] it The underlying iterator for key-value pairs
+         */
         explicit key_iterator(Iter it) : Iter(it) {}
+
+        /**
+         * @brief Dereference to get the key (const version)
+         *
+         * @return const auto& Reference to the key
+         */
         auto operator*() const -> const auto & { return Iter::operator*().first; }
+
+        /**
+         * @brief Dereference to get the key (non-const version)
+         *
+         * @return const auto& Reference to the key
+         */
         auto operator*() -> const auto & { return Iter::operator*().first; }
+
+        /**
+         * @brief Pre-increment operator
+         *
+         * @return key_iterator& Reference to this iterator
+         */
         auto operator++() -> key_iterator & {
             Iter::operator++();
             return *this;
         }
+        /**
+         * @brief Post-increment operator
+         *
+         * @return key_iterator Copy of this iterator before increment
+         */
         auto operator++(int) -> key_iterator {
             auto old = *this;
             ++*this;
@@ -31,10 +62,13 @@ namespace py {
     };
 
     /**
-     * @brief
+     * @brief Python-like dictionary implementation
      *
-     * @tparam Key
-     * @tparam T
+     * A dictionary class that extends std::unordered_map with Python-like
+     * convenience methods and functionality.
+     *
+     * @tparam Key The key type
+     * @tparam T The value type
      */
     template <typename Key, typename T> class dict : public std::unordered_map<Key, T> {
         using Self = dict<Key, T>;
@@ -45,33 +79,38 @@ namespace py {
         using key_type = Key;
 
         /**
-         * @brief Construct a new dict object
+         * @brief Default constructor
          *
+         * Creates an empty dictionary.
          */
         dict() : Base{} {}
 
         /**
-         * @brief Construct a new dict object
+         * @brief Construct a dict from an initializer list
+         *
+         * Creates a dictionary from a list of key-value pairs.
          *
-         * @param[in] init
+         * @param[in] init Initializer list of key-value pairs
          */
         dict(std::initializer_list<value_type> init) : Base{init} {}
 
         /**
-         * @brief
+         * @brief Check if the dictionary contains a specific key
          *
          * @param[in] key
-         * @return true
-         * @return false
+         * @return true if the key is contained in the dictionary, false otherwise
          */
         auto contains(const Key &key) const -> bool { return this->find(key) != this->end(); }
 
         /**
-         * @brief
+         * @brief Get a value with a default fallback
          *
-         * @param[in] key
-         * @param[in] default_value
-         * @return T
+         * Returns the value associated with the key, or the default value
+         * if the key is not found in the dictionary.
+         *
+         * @param[in] key The key to look up
+         * @param[in] default_value The default value to return if key is not found
+         * @return T The value associated with the key, or the default value
          */
         auto get(const Key &key, const T &default_value) const -> T {
             if (!contains(key)) {
@@ -81,36 +120,44 @@ namespace py {
         }
 
         /**
-         * @brief
+         * @brief Get iterator to the beginning of keys
+         *
+         * Returns an iterator that yields keys from the dictionary.
          *
-         * @return auto
+         * @return auto Iterator to the first key
          */
         auto begin() -> key_iterator<decltype(Base::begin())> {
             return key_iterator<decltype(Base::begin())>{Base::begin()};
         }
 
         /**
-         * @brief
+         * @brief Get iterator to the end of keys
+         *
+         * Returns an iterator past the last key in the dictionary.
          *
-         * @return auto
+         * @return auto Iterator past the last key
          */
         auto end() -> key_iterator<decltype(Base::end())> {
             return key_iterator<decltype(Base::end())>{Base::end()};
         }
 
         /**
-         * @brief
+         * @brief Get const iterator to the beginning of keys
+         *
+         * Returns a const iterator that yields keys from the dictionary.
          *
-         * @return auto
+         * @return auto Const iterator to the first key
          */
         auto begin() const -> key_iterator<decltype(Base::begin())> {
             return key_iterator<decltype(Base::begin())>{Base::begin()};
         }
 
         /**
-         * @brief
+         * @brief Get const iterator to the end of keys
+         *
+         * Returns a const iterator past the last key in the dictionary.
          *
-         * @return auto
+         * @return auto Const iterator past the last key
          */
         auto end() const -> key_iterator<decltype(Base::end())> {
             return key_iterator<decltype(Base::end())>{Base::end()};
@@ -200,8 +247,7 @@ namespace py {
      * @tparam T
      * @param[in] key
      * @param[in] m
-     * @return true
-     * @return false
+     * @return true if the key is contained in the dictionary, false otherwise
      */
     template <typename Key, typename T> inline auto operator<(const Key &key, const dict<Key, T> &m) noexcept
         -> bool {

include/py2cpp/enumerate.hpp

@@ -10,13 +10,12 @@ namespace py {
     namespace detail {
 
         /**
-         * @brief EnumerateIterator
+         * @brief Iterator for enumerated access to container elements
          *
-         * The code defines a struct called `EnumerateIterator` that is used to iterate
-         * over a container or range and provide the index of each element in the
-         * iteration.
+         * Provides iterator functionality that yields index-value pairs when
+         * iterating over containers, similar to Python's enumerate() function.
          *
-         * @tparam T
+         * @tparam T The container or range type to enumerate
          */
         template <typename T> struct EnumerateIterator {
             typedef decltype(std::begin(std::declval<T>())) TIter;
@@ -26,33 +25,23 @@ namespace py {
             TIter iter;
 
             /**
-             * @brief Not equal to
+             * @brief Check inequality between iterators
              *
-             * The `operator!=` function is an overloaded operator that checks for
-             * inequality between two `EnumerateIterator` objects. It compares the
-             * `iter` member of the current object with the `iter` member of the `other`
-             * object. If they are not equal, it returns `true`, indicating that the two
-             * iterators are not pointing to the same element. Otherwise, it returns
-             * `false`, indicating that the two iterators are equal.
+             * Compares the underlying iterators to determine if they point to different elements.
              *
-             * @param[in] other
-             * @return true
-             * @return false
+             * @param[in] other The other iterator to compare with
+             * @return true if the iterators are not equal, false otherwise
              */
             auto operator!=(const EnumerateIterator &other) const -> bool {
                 return iter != other.iter;
             }
 
             /**
-             * @brief
+             * @brief Pre-increment operator
              *
-             * The `operator++()` function is an overloaded operator that increments the
-             * `EnumerateIterator` object. It increases the value of the `i` member
-             * variable by 1 and advances the `iter` member variable to the next element
-             * in the iteration. It then returns a reference to the updated
-             * `EnumerateIterator` object.
+             * Increments both the index counter and the underlying iterator.
              *
-             * @return EnumerateIterator&
+             * @return EnumerateIterator& Reference to this iterator
              */
             EnumerateIterator &operator++() {
                 ++i;
@@ -61,57 +50,45 @@ namespace py {
             }
 
             /**
-             * @brief
+             * @brief Dereference operator
              *
-             * The `operator*()` function is an overloaded operator that returns the
-             * current element in the iteration as a `std::pair<size_t, iter_ref>`. The
-             * `size_t` value represents the index of the element, and the `iter_ref`
-             * value represents a reference to the element itself. This allows you to
-             * access both the index and the element in a single expression when using
-             * the `enumerate()` function.
+             * Returns a pair containing the current index and a reference to the element.
              *
-             * @return std::pair<size_t, iter_ref>
+             * @return std::pair<size_t, iter_ref> Pair of (index, element_reference)
              */
             auto operator*() -> std::pair<size_t, iter_ref> {
                 return std::pair<size_t, iter_ref>{i, *iter};
             }
         };
 
         /**
-         * @brief EnumerateIterableWrapper
+         * @brief Wrapper for making containers enumerable
          *
-         * The code defines a struct called `EnumerateIterableWrapper` that acts as a
-         * wrapper for an iterable object. It provides two member functions, `begin()`
-         * and `end()`, which return instances of the `EnumerateIterator` struct.
+         * Provides begin/end methods that return EnumerateIterator instances,
+         * enabling range-based for loops with index-value pairs.
          *
-         * @tparam T
+         * @tparam T The container type to wrap
          */
         template <typename T> struct EnumerateIterableWrapper {
             T &iterable;
 
             /**
-             * @brief begin
+             * @brief Get iterator to the beginning
              *
-             * The `begin()` function is a member function of the
-             * `EnumerateIterableWrapper` struct. It returns an instance of the
-             * `EnumerateIterator<T>` struct, which is used to iterate over the elements
-             * of the iterable object.
+             * Returns an EnumerateIterator pointing to the start of the container.
              *
-             * @return EnumerateIterator<T>
+             * @return EnumerateIterator<T> Iterator to the beginning
              */
             auto begin() const -> EnumerateIterator<T> {
                 return EnumerateIterator<T>{0, std::begin(iterable)};
             }
 
             /**
-             * @brief end
+             * @brief Get iterator to the end
              *
-             * The `end()` function is a member function of the
-             * `EnumerateIterableWrapper` struct. It returns an instance of the
-             * `EnumerateIterator<T>` struct, which is used to mark the end of the
-             * iteration over the elements of the iterable object.
+             * Returns an EnumerateIterator pointing past the end of the container.
              *
-             * @return EnumerateIterator<T>
+             * @return EnumerateIterator<T> Iterator past the end
              */
             auto end() const -> EnumerateIterator<T> {
                 return EnumerateIterator<T>{0, std::end(iterable)};
@@ -121,17 +98,14 @@ namespace py {
     }  // namespace detail
 
     /**
-     * @brief enumerate(T &iterable)
+     * @brief Create an enumerable wrapper for a container
      *
-     * The `enumerate(T &iterable)` function is a utility function that allows you
-     * to iterate over a container or range and also get the index of each element
-     * in the iteration. It returns an instance of the
-     * `detail::EnumerateIterableWrapper<T>` class, which provides a range-based for
-     * loop compatible interface.
+     * Returns a wrapper that allows iteration over container elements with their indices,
+     * similar to Python's enumerate() function.
      *
-     * @tparam T
-     * @param[in] iterable
-     * @return detail::EnumerateIterableWrapper<T>
+     * @tparam T The container type
+     * @param[in] iterable Reference to the container to enumerate
+     * @return detail::EnumerateIterableWrapper<T> Wrapper for enumerated iteration
      */
     template <typename T> inline auto enumerate(T &iterable)
         -> detail::EnumerateIterableWrapper<T> {