wip: cfg refinement + cstm concept docs

Author: SpectraL519

docs/cpp-gl/concepts.md

@@ -0,0 +1,15 @@
+# Concepts API Reference {: #concepts-api-reference }
+
+This page serves as the central index for all C++20 concepts used across the library to enforce type safety and template constraints.
+
+> [!IMPORTANT]
+> This page is maintained manually and separately from the auto-generated API reference as the [MkDoxy](https://github.com/JakubAndrysek/MkDoxy) tool does not currently support generating documentation for concepts.
+
+---
+
+## Graph Library (GL) Concepts
+
+The Graph Library (GL) module relies on concepts to validate identifier types and property structures at compile time.
+
+- **[GL Traits & Concepts Documentation](gl_traits.md)**: Full API reference for the GL module.
+    - [`gl::traits::c_id_type`](gl_traits.md#gl-traits-c-id-type): Concept defining the requirements for an identifier type.

docs/cpp-gl/gl_traits.md

@@ -0,0 +1,31 @@
+# GL Traits & Concepts Documentation {: #gl-traits-concepts-documentation }
+
+This page documents the C++20 concepts and type traits used to constrain templates across the GL library.
+
+> [!IMPORTANT]
+> This page is maintained manually and separately from the auto-generated API reference as the [MkDoxy](https://github.com/JakubAndrysek/MkDoxy) tool does not currently support generating documentation for concepts.
+
+---
+
+## **gl::traits::c_id_type** {: #gl-traits-c-id-type }
+
+**Module:** Part of the [GL-Traits](group__GL-Traits.md) group.
+
+Concept defining the requirements for an identifier type.
+
+### Detailed Description
+
+Ensures that any custom ID type provided to the graph library is an unsigned integral type to guarantee safe indexing and representation.
+
+### Template Parameters
+
+| Parameter | Description |
+| :--- | :--- |
+| `T` | The type to evaluate against the concept. |
+
+### Definition
+
+```cpp
+template <typename T>
+concept c_id_type = std::unsigned_integral<T>;
+```

docs/groups.dox

@@ -16,6 +16,7 @@
 /// @defgroup GL-Algorithm Graph Algorithms
 /// @ingroup GL
 /// @brief Common graph algorithms and algorithm-related utility.
+/// @todo Refine description
 ///
 /// Provides generic, highly customizable implementations of classic graph algorithms.
 /// This includes standard search templates (BFS, DFS, PFS), shortest path finders
@@ -44,6 +45,10 @@
 /// Encapsulates the `gl::traits` namespace. These components are used extensively throughout the
 /// library to constrain template parameters and interrogate types at compile time (e.g., deducing
 /// underlying vertex/edge types, querying graph directedness, or enforcing structural constraints).
+///
+/// @section concepts_link Detailed Concept Specifications
+/// For a detailed list of all GL module's concepts and their formal requirements, please refer to
+/// the [GL Traits & Concepts Documentation](gl_traits.md#gl-traits-concepts-documentation ) page.
 
 /// @defgroup GL-Types Generic Types
 /// @ingroup GL

include/gl/types/core.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 gl/types/core.hpp
+/// @brief Core type definitions, traits, and utilities for the GL library.
+
 #pragma once
 
 #include "gl/attributes/force_inline.hpp"
@@ -14,24 +17,58 @@
 
 namespace gl {
 
+/// @ingroup GL GL-Core
+/// @brief Type alias for the standard size type used throughout the library.
+///
+/// Used primarily for indices, counts, and sizes of graph components.
 using size_type = std::size_t;
+
+/// @ingroup GL GL-Core
+/// @brief The default unsigned integer type used for vertex and edge identifiers.
 using default_id_type = std::uint32_t;
 
+/// @namespace gl::traits
+/// @brief Contains C++20 concepts and type traits used to constrain library templates.
 namespace traits {
 
+/// @ingroup GL GL-Traits
+/// @brief Concept defining the requirements for an identifier type.
+///
+/// Ensures that any custom ID type provided to the graph library is an
+/// unsigned integral type to guarantee safe indexing and representation.
+///
+/// @tparam T The type to evaluate against the concept.
 template <typename T>
 concept c_id_type = std::unsigned_integral<T>;
 
 } // namespace traits
 
+/// @ingroup GL GL-Util
+/// @brief Converts a valid identifier to a standard size type (index).
+///
+/// Provides a safe, explicit cast from any unsigned integral ID type
+/// into a `size_type`, commonly used for array/vector lookups.
+///
+/// @param id The identifier to convert.
+/// @return The identifier statically cast to `size_type`.
 [[nodiscard]] gl_attr_force_inline constexpr size_type to_idx(traits::c_id_type auto id) noexcept {
     return static_cast<size_type>(id);
 }
 
+/// @ingroup GL GL-Util
+/// @brief Converts an integral value to a standard pointer difference type.
+///
+/// Useful for safe pointer arithmetic and offset calculations within graph data structures.
+///
+/// @param i The integral value to convert.
+/// @return The value statically cast to `std::ptrdiff_t`.
 [[nodiscard]] gl_attr_force_inline constexpr std::ptrdiff_t to_diff(std::integral auto i) noexcept {
     return static_cast<std::ptrdiff_t>(i);
 }
 
+/// @ingroup GL GL-Types
+/// @brief A type alias for a `std::pair` where both elements are of the exact same type.
+/// @tparam `T` The type of both the `first` and `second` elements in the pair.
 template <typename T>
 using homogeneous_pair = std::pair<T, T>;
 

include/gl/types/properties.hpp

@@ -13,6 +13,7 @@
 
 namespace gl {
 
+/// @brief An empty properties type.
 struct empty_properties {};
 
 struct empty_properties_map {};

include/gl/vertex_descriptor.hpp

@@ -2,7 +2,7 @@
 // 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 vertex_descriptor.hpp
+/// @file gl/vertex_descriptor.hpp
 /// @brief Defines the vertex_descriptor class, a lightweight wrapper for vertex representations in graphs.
 
 #pragma once
@@ -49,17 +49,16 @@ namespace gl {
 ///
 /// 2\. Use the arrow operator to access/modify custom property fields
 ///
-/// @tparam Properties The type of property data attached to the vertex. Defaults to `empty_properties`.
-///         Must satisfy the @ref gl::traits::c_properites "c_properties" trait.
-/// @tparam IdType The underlying integer type used for the vertex ID. Defaults to `default_id_type`.
-///         Must satisfy the @ref gl::traits::c_id_type "c_id_type" trait.
+/// ### Template Parameters
+/// | Parameter  | Description | Default | Constraint |
+/// | :--------- | :--- | :--- | :--- |
+/// | Properties | The type of property data attached to the vertex. | @ref gl::empty_properties "empty_properties" | @ref gl::traits::c_properties "c_properties" |
+/// | IdType     | The underlying integer type used for the vertex ID. | @ref gl::default_id_type "default_id_type" | [c_id_type](gl_traits.md#gl-traits-c-id-type) |
 template <
     traits::c_properties Properties = empty_properties,
     traits::c_id_type IdType = default_id_type>
 class vertex_descriptor final {
 public:
-    /// @brief Type alias for the vertex_descriptor itself.
-    using type = std::type_identity_t<vertex_descriptor<Properties, IdType>>;
     /// @brief The vertex identifier type
     using id_type = IdType;
     /// @brief The type of properties associated with the vertex.

mkdocs.yml

@@ -22,7 +22,7 @@ nav:
       - Namespaces: cpp-gl/namespaces.md
       - Classes & Structs: cpp-gl/annotated.md
       - Class Hierarchy: cpp-gl/hierarchy.md
-      # - Concepts: cpp-gl/concepts.md
+      - Concepts: cpp-gl/concepts.md
       - Files: cpp-gl/files.md
       - Todo List: cpp-gl/todo.md
       # - Bug List: cpp-gl/bug.md