wip: cfg refinement

Author: SpectraL519

include/gl/vertex_descriptor.hpp

@@ -25,10 +25,33 @@ namespace gl {
 ///
 /// **Module:** Part of the @ref GL-Core "Core Graph Components" group.
 ///
-/// The vertex_descriptor class provides a type-safe and efficient way to represent
+/// The `vertex_descriptor` class provides a type-safe and efficient way to represent
 /// vertices in graph structures. It acts as a lightweight wrapper that combines
 /// a unique identifier with optional property data, ensuring safe access and
 /// comparison operations.
+///
+/// > [!WARNING] This class is not intended to be instantiated directly.
+/// >
+/// > Instead, `vertex_descriptor` objects should be retrieved from the @ref gl::graph class instance that owns the given vertex.
+///
+/// ### Example Usage
+/// The following example demonstrates how to iterate over vertices in a graph,
+/// accessing both their structural IDs and their underlying custom properties:
+/// ```cpp
+/// for (auto v : graph.vertices()) {
+///     // Access the underlying structural ID
+///     std::cout << "Node ID: " << v.id() << " | ";
+///
+///     // Use the arrow operator to access/modify custom property fields
+///     if (v->parent == gl::invalid_id)
+///         std::cout << "ROOT | Level: " << v->level << "\n";
+///     else
+///         std::cout << "Parent: " << v->parent << " | Level: " << v->level << "\n";
+/// }
+/// ```
+///
+/// @tparam Properties The type of property data attached to the vertex. Defaults to `empty_properties`.
+/// @tparam IdType The underlying integer type used for the vertex ID. Defaults to `default_id_type`.
 template <
     traits::c_properties Properties = empty_properties,
     traits::c_id_type IdType = default_id_type>
@@ -47,23 +70,28 @@ class vertex_descriptor final {
     }
 
     /// @brief Constructs a vertex descriptor with the given ID (for empty properties).
+    /// @param id The unique identifier for the vertex.
     explicit vertex_descriptor(const id_type id)
     requires(traits::c_empty_properties<properties_type>)
     : _id(id) {}
 
     /// @brief Constructs a vertex descriptor with the given ID and properties.
+    /// @param id The unique identifier for the vertex.
+    /// @param properties A reference to the property data to associate with this vertex.
     explicit vertex_descriptor(const id_type id, properties_type& properties)
     requires(traits::c_non_empty_properties<properties_type>)
     : _id(id), _properties(properties) {}
 
     /// @brief Returns an invalid vertex descriptor (for empty properties).
+    /// @return A `vertex_descriptor` holding the `invalid_id`.
     [[nodiscard]] gl_attr_force_inline static vertex_descriptor invalid() noexcept
     requires(traits::c_empty_properties<properties_type>)
     {
         return vertex_descriptor(invalid_id);
     }
 
     /// @brief Returns an invalid vertex descriptor (for non-empty properties).
+    /// @return A `vertex_descriptor` holding the `invalid_id` and empty properties.
     [[nodiscard]] gl_attr_force_inline static vertex_descriptor invalid() noexcept
     requires(traits::c_non_empty_properties<properties_type>)
     {
@@ -85,34 +113,43 @@ class vertex_descriptor final {
     ~vertex_descriptor() = default;
 
     /// @brief Equality comparison operator.
+    /// @param other The vertex descriptor to compare against.
+    /// @return `true` if both descriptors hold the same ID, `false` otherwise.
     [[nodiscard]] gl_attr_force_inline bool operator==(const vertex_descriptor& other
     ) const noexcept {
         return this->_id == other._id;
     }
 
     /// @brief Three-way comparison operator.
+    /// @param other The vertex descriptor to compare against.
+    /// @return The strong ordering result based on the underlying IDs.
     [[nodiscard]] gl_attr_force_inline std::strong_ordering operator<=>(
         const vertex_descriptor& other
     ) const noexcept {
         return this->_id <=> other._id;
     }
 
-    /// @brief Boolean conversion operator, returns true if the vertex is valid.
+    /// @brief Boolean conversion operator.
+    /// @return `true` if the vertex is valid.
     [[nodiscard]] gl_attr_force_inline operator bool() const noexcept {
         return this->is_valid();
     }
 
     /// @brief Checks if the vertex descriptor is valid.
+    /// @return `true` if the ID is not equal to `invalid_id`.
     [[nodiscard]] gl_attr_force_inline bool is_valid() const noexcept {
         return this->_id != invalid_id;
     }
 
     /// @brief Returns the vertex ID.
+    /// @return The underlying integer ID of the vertex.
     [[nodiscard]] gl_attr_force_inline id_type id() const noexcept {
         return this->_id;
     }
 
     /// @brief Returns a reference to the vertex properties.
+    /// @return A reference to the associated `properties_type`.
+    /// @throws std::logic_error If the vertex descriptor is invalid.
     [[nodiscard]] gl_attr_force_inline properties_type& properties() const
     requires(traits::c_non_empty_properties<properties_type>)
     {
@@ -121,6 +158,8 @@ class vertex_descriptor final {
     }
 
     /// @brief Arrow operator for accessing properties.
+    /// @return A pointer to the associated `properties_type`.
+    /// @throws std::logic_error If the vertex descriptor is invalid.
     [[nodiscard]] gl_attr_force_inline properties_type* operator->() const
     requires(traits::c_non_empty_properties<properties_type>)
     {
@@ -129,6 +168,8 @@ class vertex_descriptor final {
     }
 
     /// @brief Dereference operator for accessing properties.
+    /// @return A reference to the associated `properties_type`.
+    /// @throws std::logic_error If the vertex descriptor is invalid.
     [[nodiscard]] gl_attr_force_inline properties_type& operator*() const
     requires(traits::c_non_empty_properties<properties_type>)
     {
@@ -137,6 +178,9 @@ class vertex_descriptor final {
     }
 
     /// @brief Output stream operator for vertex descriptors.
+    /// @param os The output stream.
+    /// @param vertex The vertex descriptor to write.
+    /// @return A reference to the output stream.
     friend std::ostream& operator<<(std::ostream& os, const vertex_descriptor& vertex) {
         using enum io::detail::option_bit;
 

mkdocs.yml

@@ -18,10 +18,15 @@ nav:
   #     - Overview: cpp-gl/group__hgl.md
   #     - Algorithms: cpp-gl/group__hgl__alg.md
   - API Index:
+      - Modules: cpp-gl/modules.md
       - Namespaces: cpp-gl/namespaces.md
       - Classes & Structs: cpp-gl/annotated.md
+      - Class Hierarchy: cpp-gl/hierarchy.md
+      # - Concepts: cpp-gl/concepts.md
       - Files: cpp-gl/files.md
-      # TODO: Other sections (constants, functions, modules, etc...)
+      - Todo List: cpp-gl/todo.md
+      # - Bug List: cpp-gl/bug.md
+      # - Deprecated: cpp-gl/deprecated.md
 
 theme:
   name: material
@@ -33,6 +38,8 @@ theme:
     - navigation.expand
     - search.suggest
     - content.code.copy
+    - content.code.select   # TODO: use in example
+    - content.code.annotate # TODO: use in example
   palette:
     - media: "(prefers-color-scheme: light)"
       scheme: default