io docs

Author: SpectraL519

include/gl/io/graph_fio.hpp

@@ -118,7 +118,7 @@ requires(std::same_as<Mode, append>)
 /// Saves the graph topology and optionally its properties using the Graph Specification Format (GSF).
 /// The function strictly respects the @ref gl::io::write "write" and @ref gl::io::append "append" safety guards.
 ///
-/// @tparam GraphType The underlying type of the graph being saved.
+/// @tparam GraphType The concrete type of the graph being saved. Must satisfy [**c_graph**](gl_concepts.md#hgl-traits-c-graph).
 /// @tparam Mode The save behavior tag (@ref gl::io::write "write" or @ref gl::io::append "append"). Defaults to `write`.
 /// @param graph The graph instance to serialize.
 /// @param path The filesystem path where the graph will be saved. Defaults to `"graph.gsf"`.
@@ -146,14 +146,14 @@ void save(
 ///
 /// Instantiates a new graph populated with the topology and properties read from the target GSF file.
 ///
-/// @tparam GraphType The target graph type to construct. Must match the directional nature of the saved file.
-/// @param path The filesystem path from which to load the graph. Defaults to `"graph.gsf"`.
+/// @tparam GraphType The target graph type to construct. Must match the directional nature of the saved graph.
+/// @param path The filesystem path from which to load the graph.
 /// @return A newly constructed graph populated with the file's data.
 ///
 /// @throws std::filesystem::filesystem_error If the file does not exist or is not a standard file.
 /// @throws std::ios_base::failure If the file cannot be opened or if the GSF directional discriminator mismatches `GraphType`.
 template <traits::c_graph GraphType>
-[[nodiscard]] GraphType load(const std::filesystem::path& path = "graph.gsf") {
+[[nodiscard]] GraphType load(const std::filesystem::path& path) {
     std::ifstream file = detail::open_infile(path);
 
     file >> spec_fmt;

include/hgl/io.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/io.hpp
+/// @brief Includes all I/O-related headers for hypergraph file operations.
+
 #pragma once
 
 #include "hgl/io/core.hpp"

include/hgl/io/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 hgl/io/core.hpp
+/// @brief Core I/O utilities, stream manipulators, and range formatters for hypergraphs.
+
 #pragma once
 
 #include "gl/io/options.hpp"
@@ -13,16 +16,56 @@
 
 namespace hgl::io {
 
+/// @ingroup HGL-IO
+/// @copybrief gl::io::range_formatter
+/// @see gl::io::range_formatter
+template <std::ranges::range R>
+using range_formatter = gl::io::range_formatter<R>;
+
+/// @ingroup HGL-IO
+/// @copybrief gl::io::implicit_range
+/// @see gl::io::implicit_range
 using gl::io::implicit_range;
-using gl::io::implicit_range_formatter;
-using gl::io::multiline_set_formatter;
-using gl::io::range_formatter;
+
+/// @ingroup HGL-IO
+/// @copybrief gl::io::implicit_range_formatter
+/// @see gl::io::implicit_range_formatter
+template <std::integral T>
+using implicit_range_formatter = gl::io::implicit_range_formatter<T>;
+
+/// @ingroup HGL-IO
+/// @copybrief gl::io::set_formatter
+/// @see gl::io::set_formatter
 using gl::io::set_formatter;
 
+/// @ingroup HGL-IO
+/// @copybrief gl::io::multiline_set_formatter
+/// @see gl::io::multiline_set_formatter
+using gl::io::multiline_set_formatter;
+
+/// @ingroup HGL-IO
+/// @copybrief gl::io::are_options_set
+/// @see gl::io::are_options_set
 using gl::io::are_options_set;
+
+/// @ingroup HGL-IO
+/// @copybrief gl::io::clear_options
+/// @see gl::io::clear_options
 using gl::io::clear_options;
+
+/// @ingroup HGL-IO
+/// @copybrief gl::io::is_option_set
+/// @see gl::io::is_option_set
 using gl::io::is_option_set;
-using gl::io::options_manip;
+
+/// @ingroup HGL-IO
+/// @copybrief gl::io::options_manip
+/// @see gl::io::options_manip
+using options_manip = gl::io::options_manip;
+
+/// @ingroup HGL-IO
+/// @copybrief gl::io::set_options
+/// @see gl::io::set_options
 using gl::io::set_options;
 
 namespace detail {
@@ -32,21 +75,65 @@ using gl::io::detail::option_bit;
 
 } // namespace detail
 
-using gl::io::concise;
-using gl::io::spec_fmt;
-using gl::io::verbose;
+/// @ingroup HGL-IO
+/// @brief @ref hgl::io::options_manip "Stream manipulator" to enable concise hypergraph formatting.
+///
+/// Clears all layout-specific flags to default back to a compact representation.
+///
+/// @hideinitializer
+inline constexpr options_manip concise = gl::io::concise;
+
+/// @ingroup HGL-IO
+/// @brief @ref hgl::io::options_manip "Stream manipulator" to enable verbose hypergraph formatting.
+///
+/// Modifies the stream state to output detailed structural information.
+///
+/// @hideinitializer
+inline constexpr options_manip spec_fmt = gl::io::spec_fmt;
 
-using gl::io::with_vertex_properties;
-using gl::io::without_vertex_properties;
+/// @ingroup HGL-IO
+/// @brief @ref hgl::io::options_manip "Stream manipulator" to enable the Hypergraph Specification Format (HGSF).
+///
+/// Modifies the stream to output or expect data matching the precise internal parsing format used for serialization and deserialization.
+///
+/// @hideinitializer
+inline constexpr options_manip verbose = gl::io::verbose;
 
-inline const options_manip with_hyperedge_properties =
+/// @ingroup HGL-IO
+/// @brief @ref hgl::io::options_manip "Stream manipulator" to enable the processing of vertex properties.
+/// @hideinitializer
+inline constexpr options_manip with_vertex_properties = gl::io::with_vertex_properties;
+
+/// @ingroup HGL-IO
+/// @brief @ref hgl::io::options_manip "Stream manipulator" to disable the processing of vertex properties.
+/// @hideinitializer
+inline constexpr options_manip without_vertex_properties = gl::io::without_vertex_properties;
+
+/// @ingroup HGL-IO
+/// @brief @ref hgl::io::options_manip "Stream manipulator" to enable the processing of hyperedge properties.
+/// @hideinitializer
+inline constexpr options_manip with_hyperedge_properties =
     set_options(detail::option_bit::with_connection_properties);
-inline const options_manip without_hyperedge_properties =
+
+/// @ingroup HGL-IO
+/// @brief @ref hgl::io::options_manip "Stream manipulator" to disable the processing of hyperedge properties.
+/// @hideinitializer
+inline constexpr options_manip without_hyperedge_properties =
     clear_options(detail::option_bit::with_connection_properties);
 
-using gl::io::with_properties;
-using gl::io::without_properties;
+/// @ingroup HGL-IO
+/// @brief @ref hgl::io::options_manip "Stream manipulator" to enable the processing of both vertex and hyperedge properties simultaneously.
+/// @hideinitializer
+inline constexpr options_manip with_properties = gl::io::with_properties;
+
+/// @ingroup HGL-IO
+/// @brief @ref hgl::io::options_manip "Stream manipulator" to disable the processing of both vertex and hyperedge properties simultaneously.
+/// @hideinitializer
+inline constexpr options_manip without_properties = gl::io::without_properties;
 
-using gl::io::default_options;
+/// @ingroup HGL-IO
+/// @brief @ref hgl::io::options_manip "Stream manipulator" to reset all custom graph formatting flags back to their default states.
+/// @hideinitializer
+inline constexpr options_manip default_options = gl::io::default_options;
 
 } // namespace hgl::io

include/hgl/io/hypergraph_fio.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/io/hypergraph_fio.hpp
+/// @brief File I/O utilities for safely saving and loading hypergraphs to and from files.
+
 #pragma once
 
 #include "gl/io/graph_fio.hpp"
@@ -15,8 +18,15 @@
 
 namespace hgl::io {
 
-using gl::io::append;
-using gl::io::write;
+/// @ingroup HGL-IO
+/// @copybrief gl::io::append
+/// @copydetails gl::io::append
+using append = gl::io::append;
+
+/// @ingroup HGL-IO
+/// @copybrief gl::io::write
+/// @copydetails gl::io::write
+using write = gl::io::write;
 
 namespace detail {
 
@@ -25,6 +35,19 @@ using gl::io::detail::open_outfile;
 
 } // namespace detail
 
+/// @ingroup HGL-IO
+/// @brief Serializes and saves a hypergraph to a file.
+///
+/// Writes the topology and optionally the properties of the hypergraph to the specified file using the Hypergraph Specification Format (HGSF). By default,
+/// The function strictly respects the @ref hgl::io::write "write" and @ref hgl::io::append "append" safety guards.
+///
+/// @tparam HypergraphType The concrete type of the hypergraph being saved. Must satisfy [**c_hypergraph**](hgl_concepts.md#hgl-traits-c-hypergraph).
+/// @tparam Mode The file access mode (e.g., @ref hgl::io::write "write" or @ref hgl::io::append "append").
+/// @param hypergraph The hypergraph instance to serialize.
+/// @param path The filesystem path where the hypergraph will be saved. Defaults to `"hypergraph.hgsf"`.
+/// @param options An optional initializer list of stream manipulators to configure the output (e.g., `{hgl::io::with_properties}`).
+/// @throws std::filesystem::filesystem_error If file safety checks fail (e.g., overwriting an existing file in `write` mode).
+/// @throws std::ios_base::failure If the underlying file stream cannot be opened.
 template <traits::c_hypergraph HypergraphType, traits::c_io_save_mode Mode = write>
 void save(
     const HypergraphType& hypergraph,
@@ -40,8 +63,19 @@ void save(
     file << hypergraph;
 }
 
+/// @ingroup HGL-IO
+/// @brief Deserializes and loads a hypergraph from a file.
+///
+/// Instantiates a new hypergraph populated with the topology and properties read from the target HGSF file.
+///
+/// @tparam HypergraphType The target hypergraph type to construct. Must match the directional nature of the saved hypergraph.
+/// @param path The filesystem path from which to load the hypergraph.
+/// @return A newly constructed hypergraph populated with the file's data.
+///
+/// @throws std::filesystem::filesystem_error If the file does not exist or is not a regular file.
+/// @throws std::ios_base::failure If the file cannot be opened or if the HGSF directional discriminator mismatches `HypergraphType`.
 template <traits::c_hypergraph HypergraphType>
-[[nodiscard]] HypergraphType load(const std::filesystem::path& path = "hypergraph.hgsf") {
+[[nodiscard]] HypergraphType load(const std::filesystem::path& path) {
     std::ifstream file = detail::open_infile(path);
 
     file >> gl::io::spec_fmt;

include/hgl/traits.hpp

@@ -19,6 +19,10 @@ namespace hgl {
 /// 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.
+///
+/// > [!NOTE]
+/// >
+/// > To get a detailed overview of these shared utilities, please refer to the GL module's @ref GL-Traits documentation page.
 namespace traits {
 
 using namespace gl::traits;

include/hgl/util.hpp

@@ -9,36 +9,54 @@
 
 #include "gl/util/ranges.hpp"
 
-namespace hgl::util {
+namespace hgl {
 
 /// @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;
+/// @brief General utilities, ranges, and helpers for the HGL module (originating in the GL module).
+///
+/// This namespace pulls in practical, domain-agnostic C++ **range** utilities from `gl::util`.
+/// Because hypergraphs share the same underlying memory models and algorithmic requirements as
+/// standard graphs, they seamlessly reuse the same fundamental C++20 range utilities and helpers.
+///
+/// > [!NOTE]
+/// >
+/// > To get a detailed overview of these shared utilities, please refer to the GL module's @ref GL-Util documentation page.
+namespace util {
 
-/// @ingroup HGL-Util
-/// @brief @copybrief gl::util::all_equal
-/// @see gl::util::all_equal
 using gl::util::all_equal;
+using gl::util::is_constant;
+using gl::util::range_size;
 
 /// @ingroup HGL-Util
 /// @brief @copybrief gl::util::concat_view
-/// @see gl::util::concat_view
-using gl::util::concat_view;
+/// @see gl::util::concat_view for the full type definition
+template <std::ranges::view V1, std::ranges::view V2>
+using concat_view = gl::util::concat_view<V1, V2>;
 
 /// @ingroup HGL-Util
 /// @brief @copybrief gl::util::concat_fn
-/// @see gl::util::concat_fn
-using gl::util::concat_fn;
+/// @see gl::util::concat_fn for the full type definition
+using concat_fn = gl::util::concat_fn;
 
 /// @ingroup HGL-Util
-/// @brief @copybrief gl::util::concat
-/// @see gl::util::concat
-using gl::util::concat;
-
-} // namespace hgl::util
+/// @brief Concatenates two viewable ranges into a `concat_view`.
+///
+/// ### Example usage
+/// ```cpp
+/// std::vector<int> v1 = {1, 2, 3};
+/// std::vector<int> v2 = {4, 5, 6};
+/// auto concatenated = gl::util::concat(v1, v2);
+/// for (int x : concatenated)
+///     std::cout << x << " "; // Output: 1 2 3 4 5 6
+/// ```
+///
+/// @param r1 First range to concatenate.
+/// @param r2 Second range to concatenate.
+/// @todo Replace with `std::views::concat` (C++26).
+/// ### See Also
+/// - @ref hgl::util::concat_view "concat_view": The view type that represents the concatenation of two ranges.
+/// - @ref hgl::util::concat_fn "concat_fn": A helper compile-time constant function object for creating `concat_view` instances.
+inline constexpr concat_fn concat{};
+
+} // namespace util
+} // namespace hgl