hypergraph elements and dir tags docs

Author: SpectraL519

include/gl/edge_descriptor.hpp

@@ -22,8 +22,6 @@ namespace gl {
 /// @ingroup GL GL-Core
 /// @brief A lightweight wrapper representing a graph edge with its endpoints and optional properties.
 ///
-/// **Module:** Part of the @ref GL-Core "Core Graph Components" group.
-///
 /// The `edge_descriptor` class provides a type-safe and efficient way to represent
 /// edges in both directed and undirected graph structures. It encapsulates the unique
 /// identifier of the edge, its source and target vertices, and optional property data.

include/gl/vertex_descriptor.hpp

@@ -23,16 +23,14 @@ namespace gl {
 /// @ingroup GL GL-Core
 /// @brief A lightweight wrapper around a vertex identifier with optional properties.
 ///
-/// **Module:** Part of the @ref GL-Core "Core Graph Components" group.
-///
 /// 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.
+/// > Instead, `vertex_descriptor` objects should be retrieved from the @ref gl::graph "graph" class instance that owns the given vertex.
 ///
 /// ### Example Usage
 /// ```cpp
@@ -49,7 +47,7 @@ namespace gl {
 ///
 /// 1\. Apply the stream manipulator to ensure custom property data is included in the output.
 ///
-/// 2\. Use the arrow operator `->` to read custom properties attached to the vertex.
+/// 2\. Use the arrow operator `->` to read custom properties attached to the vertex (assuming the vertex properties type contains `parent` and `level` members).
 ///
 /// 3\. Access another vertex via the `graph` using its ID, and modify the current vertex's properties.
 ///

include/hgl/directional_tags.hpp

@@ -2,22 +2,45 @@
 // This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
 // Licensed under the MIT License. See the LICENSE file in the project root for full license information.
 
+/// @file hgl/directional_tags.hpp
+/// @brief Defines tag types used to specify the directionality of a hypergraph.
+
 #pragma once
 
 #include "hgl/traits.hpp"
 
 namespace hgl {
 
+/// @ingroup HGL-Core
+/// @brief Tag type specifying that a hypergraph is undirected.
+///
+/// In an undirected hypergraph, a hyperedge is strictly defined as a set of incident vertices,
+/// with no distinction between origin and destination.
 struct undirected_t {
+    /// @brief Self type identity for internal metaprogramming use.
     using type = std::type_identity_t<undirected_t>;
 };
 
+/// @ingroup HGL-Core
+/// @brief Tag type specifying that a hypergraph is backward-forward (BF) directed.
+///
+/// In a BF-directed hypergraph, each hyperedge maps a distinct set of *tail* vertices (origins)
+/// to a distinct set of *head* vertices (destinations).
 struct bf_directed_t {
+    /// @brief Self type identity for internal metaprogramming use.
     using type = std::type_identity_t<bf_directed_t>;
 };
 
 namespace traits {
 
+/// @ingroup HGL-Traits
+/// @brief Validates if a type is a valid hypergraph directional tag.
+///
+/// The valid hypergraph directional tags are @ref hgl::undirected_t "undirected_t" and
+/// @ref hgl::bf_directed_t "bf_directed_t". This concept is used to constrain template
+/// parameters intended to specify the directionality of a hypergraph.
+///
+/// @tparam T The type to evaluate against the concept.
 template <typename T>
 concept c_hypergraph_directional_tag = c_one_of<T, undirected_t, bf_directed_t>;
 

include/hgl/hypergraph_elements.hpp

@@ -2,6 +2,9 @@
 // This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
 // Licensed under the MIT License. See the LICENSE file in the project root for full license information.
 
+/// @file hgl/hypergraph_elements.hpp
+/// @brief Defines the hyperedge_descriptor class, element tags, and aliases for hypergraph elements.
+
 #pragma once
 
 #include "gl/traits.hpp"
@@ -16,93 +19,219 @@ namespace hgl {
 
 // --- hypergraph elements ---
 
-using gl::vertex_descriptor;
-
+/// @ingroup HGL-Core
+/// @brief Type alias adapting the standard graph vertex descriptor for hypergraphs.
+///
+/// Because hypergraphs and standard graphs share the same fundamental vertex representation,
+/// this alias imports the @ref gl::vertex_descriptor type into the HGL module. It provides a
+/// type-safe wrapper combining a unique identifier with optional property data.
+///
+/// > [!WARNING] This class is not intended to be instantiated directly.
+/// >
+/// > Instead, `vertex_descriptor` objects should be retrieved from the @ref hgl::hypergraph class instance that owns the given vertex.
+///
+/// ### Example Usage
+/// ```cpp
+/// std::cout << gl::io::verbose << gl::io::with_vertex_properties; // (1)!
+///
+/// for (const auto& vertex : hypergraph.vertices()) {
+///     const auto deg = hypergraph.degree(vertex); // (2)!
+///
+///     if (deg == 0uz)
+///         vertex->description = "Isolated node"; // (3)!
+///     else
+///         vertex->description = std::format("Connected to {} hyperedges", deg);
+///
+///     std::cout << "Vertex details: " << vertex << '\n';
+/// }
+/// ```
+///
+/// 1. Stream manipulators inject persistent formatting state globally before iterating.
+/// 2. Use the owning hypergraph to query topological information about the vertex.
+/// 3. Safely access and modify the underlying properties via the `->` operator (assuming the vertex properties type contains a `description` member).
+///
+/// ### Template Parameters
+/// | Parameter | Description | Default | Constraint |
+/// | :-------- | :--- | :--- | :--- |
+/// | Properties | The type of property data attached to the vertex. | @ref hgl::empty_properties "empty_properties" | [**c_properties**](gl_concepts.md#gl-traits-c-properties) |
+/// | IdType | The underlying integer type used for the IDs. | @ref hgl::default_id_type "default_id_type" | [**c_id_type**](gl_concepts.md#gl-traits-c-id-type) |
+///
+/// ### See Also
+/// - @ref gl::vertex_descriptor for the full definition of the type.
+/// - @ref hgl::hyperedge_descriptor "hyperedge_descriptor" for the corresponding hyperedge wrapper class.
+/// - @ref hgl::hypergraph "hypergraph" for the owning hypergraph class that manages vertex descriptors.
+template <
+    traits::c_properties Properties = empty_properties,
+    traits::c_id_type IdType = default_id_type>
+using vertex_descriptor = gl::vertex_descriptor<Properties, IdType>;
+
+/// @ingroup HGL-Core
+/// @brief A lightweight wrapper representing a hypergraph edge with optional properties.
+///
+/// The `hyperedge_descriptor` class provides a type-safe and efficient way to represent
+/// hyperedges in hypergraph structures. It acts as a lightweight wrapper that encapsulates
+/// the unique identifier of the hyperedge and its optional property data, ensuring safe
+/// access and comparison operations.
+///
+/// > [!WARNING] This class is not intended to be instantiated directly.
+/// >
+/// > Instead, `hyperedge_descriptor` objects should be retrieved from the @ref hgl::hypergraph class instance that owns the given hyperedge.
+///
+/// ### Example Usage
+/// ```cpp
+/// std::cout << gl::io::verbose << gl::io::with_hyperedge_properties; // (1)!
+///
+/// for (const auto& hyperedge : hypergraph.hyperedges()) {
+///     const auto size = hypergraph.hyperedge_size(hyperedge); // (2)!
+///     hyperedge->weight = static_cast<double>(size) * 1.5; // (3)!
+///     std::cout << "Hyperedge details: " << hyperedge << '\n';
+/// }
+/// ```
+///
+/// 1. Stream manipulators like `with_hyperedge_properties` apply persistently to `std::cout`.
+/// 2. Use the owning hypergraph to query topological information about the hyperedge.
+/// 3. Update the payload properties through the overloaded `->` operator (assuming the hyperedge properties type contains a `weight` member).
+///
+/// ### Template Parameters
+/// | Parameter | Description | Default | Constraint |
+/// | :-------- | :--- | :--- | :--- |
+/// | Properties | The type of property data attached to the hyperedge. | @ref hgl::empty_properties "empty_properties" | [**c_properties**](gl_concepts.md#gl-traits-c-properties) |
+/// | IdType | The underlying integer type used for the IDs. | @ref hgl::default_id_type "default_id_type" | [**c_id_type**](gl_concepts.md#gl-traits-c-id-type) |
+///
+/// ### See Also
+/// - @ref hgl::vertex_descriptor "vertex_descriptor" for the corresponding vertex wrapper class.
+/// - @ref hgl::hypergraph "hypergraph" for the owning hypergraph class that manages hyperedge descriptors.
 template <
     traits::c_properties Properties = empty_properties,
     traits::c_id_type IdType = default_id_type>
 class hyperedge_descriptor final {
 public:
+    /// @brief Self type alias.
     using type = hyperedge_descriptor<Properties>;
+    /// @brief The underlying integer type used for the hyperedge identifier.
     using id_type = IdType;
+    /// @brief The type of property data attached to the hyperedge.
     using properties_type = Properties;
 
+    /// @brief Default constructor creating an invalid hyperedge descriptor.
     hyperedge_descriptor() {
         *this = hyperedge_descriptor::invalid();
     }
 
+    /// @brief Constructs a property-less hyperedge descriptor from a raw ID.
+    /// @param id The raw identifier of the hyperedge.
     explicit hyperedge_descriptor(const id_type id)
     requires(traits::c_empty_properties<properties_type>)
     : _id(id) {}
 
+    /// @brief Constructs a hyperedge descriptor binding an ID to its properties.
+    /// @param id The raw identifier of the hyperedge.
+    /// @param properties A reference to the underlying properties payload.
     explicit hyperedge_descriptor(const id_type id, properties_type& properties)
     requires(traits::c_non_empty_properties<properties_type>)
     : _id(id), _properties(properties) {}
 
+    /// @brief Returns a special descriptor representing an invalid or uninitialized property-less hyperedge.
+    /// @return An invalid `hyperedge_descriptor`.
     [[nodiscard]] gl_attr_force_inline static hyperedge_descriptor invalid() noexcept
     requires(traits::c_empty_properties<properties_type>)
     {
         return hyperedge_descriptor(invalid_id);
     }
 
+    /// @brief Returns a special descriptor representing an invalid or uninitialized hyperedge with properties.
+    /// @return An invalid `hyperedge_descriptor`.
     [[nodiscard]] gl_attr_force_inline static hyperedge_descriptor invalid() noexcept
     requires(traits::c_non_empty_properties<properties_type>)
     {
         static properties_type invalid_properties{};
         return hyperedge_descriptor(invalid_id, invalid_properties);
     }
 
+    /// @brief Default copy constructor.
     hyperedge_descriptor(const hyperedge_descriptor&) = default;
+    /// @brief Default copy assignment operator.
     hyperedge_descriptor& operator=(const hyperedge_descriptor&) = default;
 
+    /// @brief Default move constructor.
     hyperedge_descriptor(hyperedge_descriptor&&) noexcept = default;
+    /// @brief Default move assignment operator.
     hyperedge_descriptor& operator=(hyperedge_descriptor&&) noexcept = default;
 
+    /// @brief Default destructor.
     ~hyperedge_descriptor() = default;
 
+    /// @brief Compares two hyperedge descriptors for equality.
+    /// @param other The descriptor to compare against.
+    /// @return `true` if both descriptors hold the same ID, `false` otherwise.
     [[nodiscard]] bool operator==(const hyperedge_descriptor& other) const noexcept {
         return this->_id == other._id;
     }
 
+    /// @brief Contextually converts the descriptor to a boolean.
+    /// @return `true` if the descriptor is valid, `false` otherwise.
     [[nodiscard]] gl_attr_force_inline operator bool() const noexcept {
         return this->is_valid();
     }
 
+    /// @brief Compares two hyperedge descriptors to establish a strict ordering based on their IDs.
+    /// @param other The descriptor to compare against.
+    /// @return The result of the three-way comparison between the underlying IDs.
     [[nodiscard]] gl_attr_force_inline std::strong_ordering operator<=>(
         const hyperedge_descriptor& other
     ) const noexcept {
         return this->_id <=> other._id;
     }
 
+    /// @brief Checks if the descriptor represents a valid hyperedge.
+    /// @return `true` if the underlying ID is not the invalid ID constant, `false` otherwise.
     [[nodiscard]] gl_attr_force_inline bool is_valid() const noexcept {
         return this->_id != invalid_id;
     }
 
+    /// @brief Retrieves the raw underlying ID of the hyperedge.
+    /// @return The hyperedge's integer ID.
     [[nodiscard]] gl_attr_force_inline id_type id() const noexcept {
         return this->_id;
     }
 
+    /// @brief Retrieves a reference to the property payload attached to the hyperedge.
+    /// @return A mutable reference to the underlying properties.
+    /// @throws std::logic_error If the descriptor is invalid.
     [[nodiscard]] gl_attr_force_inline properties_type& properties() const
     requires(traits::c_non_empty_properties<properties_type>)
     {
         this->_validate();
         return this->_properties.get();
     }
 
+    /// @brief Arrow operator providing direct access to the hyperedge's properties.
+    /// @return A pointer to the underlying properties.
+    /// @throws std::logic_error If the descriptor is invalid.
     [[nodiscard]] gl_attr_force_inline properties_type* operator->() const
     requires(traits::c_non_empty_properties<properties_type>)
     {
         this->_validate();
         return &this->_properties.get();
     }
 
+    /// @brief Dereference operator providing direct access to the hyperedge's properties.
+    /// @return A reference to the underlying properties.
+    /// @throws std::logic_error If the descriptor is invalid.
     [[nodiscard]] gl_attr_force_inline properties_type& operator*() const
     requires(traits::c_non_empty_properties<properties_type>)
     {
         this->_validate();
         return this->_properties.get();
     }
 
+    /// @brief Serializes the hyperedge descriptor to an output stream.
+    ///
+    /// Depending on active stream flags, this outputs the descriptor in verbose or concise formats.
+    ///
+    /// @param os The target output stream.
+    /// @param hyperedge The hyperedge descriptor to format.
+    /// @return The stream reference for chaining.
     friend std::ostream& operator<<(std::ostream& os, const hyperedge_descriptor& hyperedge) {
         using enum io::detail::option_bit;
 
@@ -154,15 +283,29 @@ class hyperedge_descriptor final {
 
 // --- hypergraph element tags ---
 
+/// @ingroup HGL-Core
+/// @brief Tag type representing a vertex element in a hypergraph.
 struct vertex_t {};
 
+/// @ingroup HGL-Core
+/// @brief Tag type representing a hyperedge element in a hypergraph.
 struct hyperedge_t {};
 
+/// @ingroup HGL-Core
+/// @brief A constant instance of `vertex_t` used for tagging and generic dispatching.
 inline constexpr vertex_t vertex{};
+/// @ingroup HGL-Core
+/// @brief A constant instance of `hyperedge_t` used for tagging and generic dispatching.
 inline constexpr hyperedge_t hyperedge{};
 
 namespace traits {
 
+/// @ingroup HGL-Traits
+/// @brief Validates if a type is a valid hypergraph element tag.
+///
+/// The valid hypergraph element tags are @ref hgl::vertex_t "vertex_t" and @ref hgl::hyperedge_t "hyperedge_t".
+///
+/// @tparam T The type to evaluate against the concept.
 template <typename T>
 concept c_hypergraph_element_tag = c_one_of<T, vertex_t, hyperedge_t>;
 

include/hgl/traits.hpp

@@ -8,7 +8,6 @@
 #pragma once
 
 #include "gl/traits.hpp"
-#include "hgl/types.hpp"
 
 namespace hgl {