init hgl groups + first hgl doc comments

Author: SpectraL519

docs/config/groups.dox

@@ -44,12 +44,12 @@
 
 /// @defgroup GL-IO I/O Utility
 /// @ingroup GL
-/// @brief Comprehensive I/O stream support, parsing algorithms, and range-based formatting.
+/// @brief I/O stream operations, formatting, and serialization of graph data.
 ///
 /// This group provides the necessary infrastructure to seamlessly serialize, deserialize, and
-/// visualize complex graph structures. By offering a robust set of stream manipulators, formatting
-/// traits, and configuration options, it allows users to easily translate in-memory graphs to
-/// and from standard streams, files, or custom string representations.
+/// visualize complex graph structures. By offering a robust set of stream manipulators, range
+/// formatting utilities, and configuration options, it allows users to easily translate
+/// in-memory graphs to and from standard streams, files, or custom string representations.
 
 /// @defgroup GL-Traits Traits & Concepts
 /// @ingroup GL
@@ -83,3 +83,78 @@
 /// operations, these utilities are completely independent of graph theory semantics. They provide
 /// a curated set of highly reusable, general-purpose tools that can smoothly integrate into any
 /// modern C++ codebase.
+
+/// @defgroup HGL Hypergraph Library (HGL)
+/// @brief The top-level module defining the general-purpose C++ template hypergraph library.
+///
+/// This module provides a comprehensive suite of memory-efficient hypergraph representations,
+/// highly customizable algorithms, and robust I/O facilities. Designed strictly around modern
+/// C++ paradigms, the library leverages templates and concepts to deliver an API that is fast,
+/// generic, and type-safe. It supports both undirected hypergraphs and backward-forward (bf)
+/// directed hypergraphs.
+
+/// @defgroup HGL-Core Core Hypergraph Components
+/// @ingroup HGL
+/// @brief Fundamental hypergraph data structures, element descriptors, and configuration tags.
+///
+/// This group establishes the primary user interface for the HGL module, centered around the highly
+/// configurable @ref hgl::hypergraph "hypergraph" class. It provides the core data types, such as vertex
+/// and hyperedge descriptors, required to safely navigate and manipulate graph elements.
+///
+/// Furthermore, this module defines the declarative tags (e.g., directedness and backend
+/// implementation types) that dictate both the behavioral semantics and the underlying memory
+/// layout of the instantiated hypergraphs.
+
+/// @defgroup HGL-Algorithm Hypergraph Algorithms
+/// @ingroup HGL
+/// @brief Generic hypergraph algorithms, search templates, and related utilities.
+///
+/// This module provides hypergraph-specific algorithmic templates and implementations
+/// (such as forward and backward searches) designed to natively navigate the complex,
+/// high-order structure of hyperedges.
+
+/// @defgroup HGL-IO I/O Utility
+/// @ingroup HGL
+/// @brief I/O stream operations, formatting, and serialization of hypergraph data.
+///
+/// Provides the necessary infrastructure to seamlessly serialize, deserialize, and visualize
+/// complex hypergraph structures. It utilizes shared stream manipulation options and range
+/// formatting utilities to easily translate in-memory hypergraphs to and from standard
+/// streams and files.
+
+/// @defgroup HGL-Traits Traits & Concepts
+/// @ingroup HGL
+/// @brief Type traits, template constraints, and compile-time metaprogramming utilities.
+///
+/// These components form the strict conceptual backbone of the HGL module, used extensively
+/// to ensure internal type safety and correctness, while also constraining user-defined types
+/// to required structural contracts.
+///
+/// @section concepts_link Detailed Concept Specifications
+/// For a detailed list of all HGL module's concepts and their formal requirements, please refer to
+/// the [HGL Concepts Documentation](hgl_concepts.md#hgl-concepts-documentation) page.
+///
+/// > [!NOTE]
+/// >
+/// > Because hypergraphs share the same underlying implementation design and mechanisms as standard
+/// > graphs, they seamlessly reuse the same fundamental C++20 concepts. Therefore the HGL module
+/// > pulls in all standard graph traits, concept checkers, and metaprogramming utilities from the
+/// > GL module. To get an overview of these traits and concepts, please refer to the GL module's
+/// > @ref GL-Traits documentation page.
+
+/// @defgroup HGL-Types Generic Types
+/// @ingroup HGL
+/// @brief Independent, high-performance data structures and utility types.
+///
+/// This module houses a variety of general-purpose data structures and types. Though they are
+/// utilized natively by hypergraph implementations, these components are carefully decoupled
+/// from specific hypergraph logic, they can be seamlessly extracted and utilized in broader
+/// contexts.
+
+/// @defgroup HGL-Util General Utilities
+/// @ingroup HGL
+/// @brief Practical, domain-agnostic C++ helpers, mathematical functions, and polyfills.
+///
+/// These utilities provide a curated set of general-purpose tools that support the
+/// library's internal algorithms and hypergraph modeling operations, completely
+/// independent of strict hypergraph theory semantics.

include/gl/constants.hpp

@@ -38,7 +38,7 @@ struct initial_id_t {
 };
 
 /// @ingroup GL GL-Core
-/// @brief A constant instance of `initial_id_t` that can be used to represent the initial ID value of 0 for graph elements in a type-safe manner.
+/// @brief An `initial_id_t` tag constant that can be used to represent the initial ID value of 0 for graph elements in a type-safe manner.
 ///
 /// ### Example Usage
 /// ```cpp
@@ -96,7 +96,7 @@ struct invalid_id_t {
 };
 
 /// @ingroup GL GL-Core
-/// @brief A constant instance of `invalid_id_t` that can be used to represent the invalid ID value for graph elements in a type-safe manner.
+/// @brief An `invalid_id_t` tag constant that can be used to represent the invalid ID value for graph elements in a type-safe manner.
 ///
 /// ### Example Usage
 /// ```cpp

include/gl/types/properties.hpp

@@ -17,16 +17,16 @@
 namespace gl {
 
 /// @ingroup GL GL-Core
-/// @brief A tag struct representing no user-defined properties.
+/// @brief A stateless, empty structural tag representing an absence of properties.
 ///
 /// > [!IMPORTANT]
 /// >
 /// > This type is used as a default `properties_type` for graph components that do not require any user-defined data.
-/// > It serves as a marker to indicate that the component is "property-less" and can be optimized accordingly.
+/// > It serves as a marker to indicate that the component is *property-less* and can be optimized accordingly.
 struct empty_properties {};
 
 /// @ingroup GL GL-Core
-/// @brief A tag struct representing an empty property map.
+/// @brief A stateless, empty structural tag indicating that the absence of a property map container.
 ///
 /// > [!NOTE]
 /// >

include/gl/util/ranges.hpp

@@ -13,7 +13,7 @@
 namespace gl::util {
 
 /// @ingroup GL GL-Util
-/// @brief Returns the size of a range.
+/// @brief Safely determines the size of a range.
 ///
 /// This function returns the size of a range if it is a sized range, otherwise it computes the
 /// distance between the beginning and end of the range. Note that computing the distance for

include/hgl/constants.hpp

@@ -2,19 +2,44 @@
 // 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/constants.hpp
+/// @brief Defines common constant values and types used across the HGL module.
+
 #pragma once
 
 #include "gl/constants.hpp"
 #include "hgl/traits.hpp"
 
 namespace hgl {
 
-using gl::initial_id;
-using gl::initial_id_t;
+/// @ingroup HGL-Core
+/// @brief A constant representing the initial ID value of 0 for hypergraph elements.
+/// @see gl::initial_id_v
 using gl::initial_id_v;
 
-using gl::invalid_id;
-using gl::invalid_id_t;
+/// @ingroup HGL-Core
+/// @brief A helper type that can be implicitly converted to the initial ID value of 0 for any valid ID type.
+/// @see gl::initial_id_t
+using gl::initial_id_t;
+
+/// @ingroup HGL-Core
+/// @brief An `initial_id_t` tag constant that can be used to represent the initial ID value of 0 for hypergraph elements in a type-safe manner.
+/// @see gl::initial_id
+using gl::initial_id;
+
+/// @ingroup HGL-Core
+/// @brief A constant representing the invalid ID value for hypergraph elements, defined as the maximum value of the specified ID type.
+/// @see gl::invalid_id_v
 using gl::invalid_id_v;
 
+/// @ingroup HGL-Core
+/// @brief A helper type that can be implicitly converted to the invalid ID value for any valid ID type.
+/// @see gl::invalid_id_t
+using gl::invalid_id_t;
+
+/// @ingroup HGL-Core
+/// @brief An `invalid_id_t` tag constant that can be used to represent the invalid ID value for hypergraph elements in a type-safe manner.
+/// @see gl::invalid_id
+using gl::invalid_id;
+
 } // namespace hgl

include/hgl/conversion.hpp

@@ -231,7 +231,7 @@ template <traits::c_hypergraph_impl_tag TargetImplTag, traits::c_hypergraph Hype
 
 template <gl::traits::c_undirected_graph G>
 [[nodiscard]] G projection(const traits::c_undirected_hypergraph auto& h) {
-    using edge_vertices = hgl::homogeneous_pair<typename G::id_type>;
+    using edge_vertices = homogeneous_pair<typename G::id_type>;
     std::vector<edge_vertices> edges;
 
     for (const auto eid : h.hyperedge_ids()) {
@@ -263,7 +263,7 @@ requires std::same_as<typename G::traits_type::implementation_tag, gl::impl::fla
 
 template <gl::traits::c_directed_graph G>
 [[nodiscard]] G projection(const traits::c_bf_directed_hypergraph auto& h) {
-    using edge_vertices = hgl::homogeneous_pair<typename G::id_type>;
+    using edge_vertices = homogeneous_pair<typename G::id_type>;
     std::vector<edge_vertices> edges;
 
     for (const auto eid : h.hyperedge_ids()) {

include/hgl/traits.hpp

@@ -2,13 +2,27 @@
 // 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/traits.hpp
+/// @brief Contains C++20 concepts and type traits used to constrain hypergraph library templates.
+
 #pragma once
 
 #include "gl/traits.hpp"
 #include "hgl/types.hpp"
 
-namespace hgl::traits {
+namespace hgl {
+
+/// @ingroup HGL-Traits
+/// @brief Traits and concepts for the HGL module.
+///
+/// This namespace contains the definitions of all hypergraph-specifc concepts and type traits
+/// used to constrain library types and pulls in all standard graph traits, concept checkers,
+/// and metaprogramming utilities from `gl::traits`. Because hypergraphs share the same underlying
+/// implementation design and mechanisms as standard graphs, they seamlessly reuse the same
+/// fundamental C++20 concepts.
+namespace traits {
 
 using namespace gl::traits;
 
-} // namespace hgl::traits
+} // namespace traits
+} // namespace hgl

include/hgl/types.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/types.hpp
+/// @brief Core type definitions, generic data structures, and properties for the HGL module.
+
 #pragma once
 
 #include "gl/types/core.hpp"
@@ -13,27 +16,81 @@ namespace hgl {
 
 // --- core types ---
 
-using gl::default_id_type;
+/// @ingroup HGL-Types
+/// @brief @copybrief gl::size_type
+///
+/// Used primarily for indices, counts, and sizes of hypergraph components.
+/// @see gl::size_type
 using gl::size_type;
 
-using gl::to_diff;
+/// @ingroup HGL-Types
+/// @brief The default unsigned integer type used for vertex and hyperedge identifiers.
+/// @see gl::default_id_type
+using gl::default_id_type;
+
+/// @ingroup HGL-Types
+/// @brief @copybrief gl::to_idx
+/// @see gl::to_idx
 using gl::to_idx;
 
+/// @ingroup HGL-Types
+/// @brief @copybrief gl::to_diff
+/// @see gl::to_diff
+using gl::to_diff;
+
 // --- generic data structures ---
 
+/// @ingroup HGL-Types
+/// @brief @copybrief gl::flat_jagged_vector
+/// @see gl::flat_jagged_vector
 using gl::flat_jagged_vector;
+
+/// @ingroup HGL-Types
+/// @brief @copybrief gl::flat_matrix
+/// @see gl::flat_matrix
 using gl::flat_matrix;
+
+/// @ingroup HGL-Types
+/// @brief @copybrief gl::homogeneous_pair
+/// @see gl::homogeneous_pair
 using gl::homogeneous_pair;
 
 // --- property types ---
 
-using gl::bin_color_value;
-using gl::binary_color;
-using gl::binary_color_property;
-using gl::dynamic_properties;
+/// @ingroup HGL-Core
+/// @brief @copybrief gl::empty_properties
+///
+/// > [!IMPORTANT]
+/// >
+/// > This type is used as a default `properties_type` for hypergraph components that do not require any user-defined data.
+/// > It serves as a marker to indicate that the component is *property-less* and can be optimized accordingly.
+///
+/// @see gl::empty_properties
 using gl::empty_properties;
+
+/// @ingroup HGL-Core
+/// @brief @copybrief gl::empty_properties_map
+///
+/// > [!NOTE]
+/// >
+/// > This type is used internally by the library to optimize storage for hypergraph components that have no properties.
+///
+/// @see gl::empty_properties_map
 using gl::empty_properties_map;
+
+/// @ingroup HGL-Core
+/// @brief @copybrief gl::name_property
+/// @see gl::name_property
 using gl::name_property;
+
+/// @ingroup HGL-Core
+/// @brief @copybrief gl::dynamic_properties
+/// @see gl::dynamic_properties
+using gl::dynamic_properties;
+
+/// @ingroup HGL-Core
+/// @brief A property struct providing arithmetic weight for hyperedges or vertices.
+/// @see gl::weight_property
 using gl::weight_property;
 
 } // namespace hgl

include/hgl/util.hpp

@@ -2,16 +2,43 @@
 // 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/util.hpp
+/// @brief Defines utility functions and views for working with C++20 ranges in the HGL module.
+
 #pragma once
 
 #include "gl/util/ranges.hpp"
 
 namespace hgl::util {
 
+/// @ingroup HGL-Util
+/// @brief @copybrief gl::util::range_size
+/// @see gl::util::range_size
+using gl::util::range_size;
+
+/// @ingroup HGL-Util
+/// @brief @copybrief gl::util::is_constant
+/// @see gl::util::is_constant
+using gl::util::is_constant;
+
+/// @ingroup HGL-Util
+/// @brief @copybrief gl::util::all_equal
+/// @see gl::util::all_equal
 using gl::util::all_equal;
-using gl::util::concat;
+
+/// @ingroup HGL-Util
+/// @brief @copybrief gl::util::concat_view
+/// @see gl::util::concat_view
 using gl::util::concat_view;
-using gl::util::is_constant;
-using gl::util::range_size;
+
+/// @ingroup HGL-Util
+/// @brief @copybrief gl::util::concat_fn
+/// @see gl::util::concat_fn
+using gl::util::concat_fn;
+
+/// @ingroup HGL-Util
+/// @brief @copybrief gl::util::concat
+/// @see gl::util::concat
+using gl::util::concat;
 
 } // namespace hgl::util

mkdocs.yml

@@ -36,6 +36,14 @@ nav:
           - Generic Templates: hgl/algorithms/templates.md
           - Concrete Traversals: hgl/algorithms/traversal.md
       - I/O Utility: hgl/io.md
+      - API Reference:
+          - Overview: cpp-gl/group__HGL.md
+          - Core Components: cpp-gl/group__HGL-Core.md
+          - Algorithms: cpp-gl/group__HGL-Algorithm.md
+          - I/O Utility: cpp-gl/group__HGL-IO.md
+          - Traits & Concepts: cpp-gl/group__HGL-Traits.md
+          - Generic Types: cpp-gl/group__HGL-Types.md
+          - General Utilities: cpp-gl/group__HGL-Util.md
   - API Index:
       - Modules: cpp-gl/modules.md
       - Classes & Structs: cpp-gl/annotated.md