impl tags docs refinement

Author: SpectraL519

include/hgl/hypergraph.hpp

@@ -210,10 +210,6 @@ struct to_impl;
 /// | HypergraphTraits | The core configuration type specifying the behavior and representation of the hypergraph.  | [**c_instantiation_of<hypergraph_traits>**](gl_concepts.md#gl-traits-c-instantiation-of) |
 ///
 /// ### See Also
-/// - @ref hgl::hypergraph_traits "hypergraph_traits" for configuring the underlying properties and tags.
-/// - @ref gl::io::options_manip "options_manip" for custom stream formatting options.
-///
-/// ### See Also
 /// - @ref hgl::undirected_hypergraph "undirected_hypergraph" : Convenience alias for undirected hypergraphs.
 /// - @ref hgl::bf_directed_hypergraph "bf_directed_hypergraph" : Convenience alias for BF-directed hypergraphs.
 /// - @ref hgl::clone "clone" : Create a deep copy of a hypergraph.

include/hgl/impl/impl_tags.hpp

@@ -19,6 +19,14 @@ namespace hgl::impl {
 /// @ingroup HGL-Core
 /// @headerfile hgl/impl/impl_tags.hpp
 /// @brief Tag struct for the standard incidence list hypergraph implementation.
+///
+/// ### Layout Implications
+/// The chosen layout significantly impacts memory usage and query performance:
+///
+/// - @ref hgl::impl::bidirectional_t "bidirectional_t" (Default): Maintains two internal lists (vertex-to-hyperedges and hyperedge-to-vertices). Provides optimal $O(1)$ degree/size lookups and fast traversals in both directions at the cost of doubled memory consumption.
+/// - @ref hgl::impl::vertex_major_t "vertex_major_t": Maintains only a vertex-to-hyperedges list. Highly memory efficient and fast for querying vertex degrees or incident hyperedge sets, but querying hyperedge sizes or incident vertex setss requires expensive full-hypergraph scans.
+/// - @ref hgl::impl::hyperedge_major_t "hyperedge_major_t": Maintains only a hyperedge-to-vertices list. Memory efficient and fast for hyperedge-centric queries, but querying vertex degrees or incident hyperedge sets requires full-hypergraph scans.
+///
 /// @tparam LayoutTag Specifies the memory layout orientation for the underlying data structure.
 /// @tparam IdType The underlying integer type used for identifiers.
 template <traits::c_hypergraph_layout_tag LayoutTag, traits::c_id_type IdType>
@@ -40,6 +48,14 @@ struct list_t {
 /// @ingroup HGL-Core
 /// @headerfile hgl/impl/impl_tags.hpp
 /// @brief Tag struct for the flattened incidence list hypergraph implementation.
+///
+/// ### Layout Implications
+/// The chosen layout significantly impacts memory usage and query performance:
+///
+/// - @ref hgl::impl::bidirectional_t "bidirectional_t" (Default): Maintains two internal flattened lists (vertex-to-hyperedges and hyperedge-to-vertices). Provides optimal $O(1)$ degree/size lookups and fast traversals in both directions at the cost of doubled memory consumption.
+/// - @ref hgl::impl::vertex_major_t "vertex_major_t": Maintains only a vertex-to-hyperedges flattened list. Highly memory efficient and fast for querying vertex degrees or incident hyperedge sets, but querying hyperedge sizes or incident vertex sets requires expensive full-graph scans.
+/// - @ref hgl::impl::hyperedge_major_t "hyperedge_major_t": Maintains only a hyperedge-to-vertices flattened list. Memory efficient and fast for hyperedge-centric queries, but querying vertex degrees or incident hyperedge sets requires full-graph scans.
+///
 /// @tparam LayoutTag Specifies the memory layout orientation for the underlying data structure.
 /// @tparam IdType The underlying integer type used for identifiers.
 /// @see @ref gl::flat_jagged_vector "flat_jagged_vector" for the data structure used for the underlying model implementation.
@@ -62,6 +78,13 @@ struct flat_list_t {
 /// @ingroup HGL-Core
 /// @headerfile hgl/impl/impl_tags.hpp
 /// @brief Tag struct for the standard incidence matrix hypergraph implementation.
+///
+/// ### Layout Implications
+/// Matrix implementations strictly require an asymmetric layout tag to define the row and column dimensions of the underlying matrix:
+///
+/// - @ref hgl::impl::hyperedge_major_t "hyperedge_major_t" (Default): Stores a \f$\vert E \vert \times \vert V \vert\f$ matrix, where hyperedges are mapped to rows and vertices to columns. Retrieving the vertices incident to a specific hyperedge translates to a fast, cache-friendly contiguous memory read across a single row.
+/// - @ref hgl::impl::vertex_major_t "vertex_major_t": Stores a \f$\vert V \vert \times \vert E \vert\f$ matrix, where vertices are mapped to rows and hyperedges to columns. Retrieving the hyperedges incident to a specific vertex translates to a fast, contiguous memory read.
+///
 /// @tparam LayoutTag Specifies the memory layout orientation for the underlying data structure (must be asymmetric).
 /// @tparam IdType The underlying integer type used for identifiers.
 template <traits::c_hypergraph_asymmetric_layout_tag LayoutTag, traits::c_id_type IdType>
@@ -83,6 +106,13 @@ struct matrix_t {
 /// @ingroup HGL-Core
 /// @headerfile hgl/impl/impl_tags.hpp
 /// @brief Tag struct for the flattened incidence matrix hypergraph implementation.
+///
+/// ### Layout Implications
+/// Matrix implementations strictly require an asymmetric layout tag to define the row and column dimensions of the underlying matrix:
+///
+/// - @ref hgl::impl::hyperedge_major_t "hyperedge_major_t" (Default): Stores a \f$\vert E \vert \times \vert V \vert\f$ flat matrix, where hyperedges are mapped to rows and vertices to columns. Retrieving the vertices incident to a specific hyperedge translates to a fast, cache-friendly contiguous memory read across a single row.
+/// - @ref hgl::impl::vertex_major_t "vertex_major_t": Stores a \f$\vert V \vert \times \vert E \vert\f$ flat matrix, where vertices are mapped to rows and hyperedges to columns. Retrieving the hyperedges incident to a specific vertex translates to a fast, contiguous memory read.
+///
 /// @tparam LayoutTag Specifies the memory layout orientation for the underlying data structure (must be asymmetric).
 /// @tparam IdType The underlying integer type used for identifiers.
 /// @see @ref gl::flat_matrix "flat_matrix" for the data structure used for the underlying model implementation.