Update Doxygen documentation

Author: glynos

docs/Doxyfile.in

@@ -68,7 +68,7 @@ master_doc = 'index'
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

docs/conf.py.in

@@ -6,12 +6,15 @@ Description
 
 The core of the ``skyr`` library is a ``skyr::parse`` function
 that parses an input string and creates a ``skyr::url_record``
-that contains a URL parts, and a ``skyr::serialize`` function
+that contains URL parts, and a ``skyr::serialize`` function
 that composes a URL string from an existing ``skyr::url_record``.
 
+The ``skyr::parse`` function returns ``std::expected<url_record, url_parse_errc>``
+for type-safe error handling without exceptions.
+
 Use these functions directly if your needs are simple. Use the
 ``skyr::url`` class for more complex operations, including
-Unicode encoding and decoding.
+Unicode encoding and decoding, URL transformations, and sanitization.
 
 Headers
 -------
@@ -31,20 +34,30 @@ Example
     #include <skyr/core/url_record.hpp>
     #include <skyr/core/parse.hpp>
     #include <skyr/core/serialize.hpp>
-    #include <iostream>
+    #include <print>
 
     int main() {
-      auto url = skyr::url_parse("http://example.org/");
-      std::cout << url << std::endl;
-      std::cout << "Scheme:     " << url.scheme << std::endl;
-      std::cout << "Hostname:   " << url.host.value().to_string());
-      std::cout << "Pathname:   ";
-      for (const auto &path : url.path) {
-        << std::cout << "/" << path;
-      }
-      std::cout << std::endl;
+      auto result = skyr::parse("http://example.org/path/to/file");
+
+      if (result) {
+        const auto& url = result.value();
+
+        std::println("Scheme:   {}", url.scheme);
 
-      std::cout << "Serializer: " << skyr::serialize(url) << std::endl;
+        if (url.host) {
+          std::println("Hostname: {}", url.host->serialize());
+        }
+
+        std::print("Pathname: ");
+        for (const auto& segment : url.path) {
+          std::print("/{}", segment);
+        }
+        std::println("");
+
+        std::println("Serialized: {}", skyr::serialize(url));
+      } else {
+        std::println("Parse error: {}", result.error());
+      }
     }
 
 API

docs/core.rst

@@ -25,27 +25,25 @@ Example
 .. code-block:: c++
 
    #include <skyr/domain/domain.hpp>
-   #include <iostream>
+   #include <print>
 
    int main() {
      using namespace std::string_literals;
 
      auto domain = "उदाहरण.परीक्षा"s;
      auto encoded = skyr::domain::domain_to_ascii(domain);
      if (encoded) {
-       std::cout << encoded.value() << std::endl;
+       std::println(encoded.value());
      }
    }
 
 API
 ---
 
-Domain to ASCII
-^^^^^^^^^^^^^^^
+Domain Processing Functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. doxygenfunction:: skyr::domain_to_ascii(std::string_view, bool)
-
-.. doxygenfunction:: skyr::domain_to_unicode(std::string_view, bool)
+The library provides the following domain processing functions. See the header files for detailed documentation of all overloads.
 
 Error codes
 ^^^^^^^^^^^

docs/domain.rst

@@ -21,12 +21,12 @@ Example
 
    #include <skyr/url.hpp>
    #include <skyr/filesystem/path.hpp>
-   #include <iostream>
+   #include <print>
 
    int main() {
      auto path = std::filesystem::path("/usr/bin/clang");
      auto url = skyr::filesystem::from_path(path).value();
-     std::cout << url << std::endl;
+     std::println(url);
    }
 
 API

docs/filesystem.rst

@@ -14,15 +14,18 @@ This library provides:
 - A `skyr::url` class that implements a generic URL parser,
   conforming with the WhatWG URL specification
 - URL serialization and comparison
+- **Immutable URL transformations** with `with_*` methods for functional-style URL building
+- **URL sanitization** methods to remove credentials, fragments, and query parameters
+- **Custom `std::format` support** with format specifiers for URL components
 - Percent encoding and decoding functions
 - IDNA and Punycode functions for domain name parsing
-- Basic Unicode conversion functions
+- Unicode conversion utilities
 
 Quick Start
 -----------
 
-This project requires the availability of a C++17 compliant compiler
-and standard library.
+This project requires a **C++23 compliant compiler** (GCC 13+, Clang 19+, MSVC 2022+)
+and has **zero external dependencies** for core URL parsing.
 
 1. Download ``vcpkg`` and install the dependencies
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -45,36 +48,24 @@ and standard library.
    // url_test.cpp
 
    #include <skyr/url.hpp>
-   #include <skyr/percent_encoding/percent_decode.hpp>
-   #include <iostream>
+   #include <skyr/url_format.hpp>
+   #include <print>
 
    int main() {
-     using namespace skyr::literals;
-
-     try {
-       auto url =
-           "http://sub.example.إختبار:8090/\xcf\x80?a=1&c=2&b=\xe2\x80\x8d\xf0\x9f\x8c\x88"_url;
-
-       std::cout << "Protocol: " << url.protocol() << std::endl;
-
-       std::cout << "Domain?   " << std::boolalpha << url.is_domain() << std::endl;
-       std::cout << "Domain:   " << url.hostname() << std::endl;
-       std::cout << "Domain:   "
-                 << skyr::domain_to_u8(url.hostname()).value() << std::endl;
-
-       std::cout << "Port:     " << url.port<std::uint16_t>().value() << std::endl;
-
-       std::cout << "Pathname: "
-                 << skyr::percent_decode<std::string>(url.pathname()).value() << std::endl;
-
-       std::cout << "Search parameters" << std::endl;
-       const auto &search = url.search_parameters();
-       for (const auto &[key, value] : search) {
-         std::cout << "  " << "key: " << key << ", value = " << value << std::endl;
-       }
-     }
-     catch (const skyr::url_parse_error &e) {
-       std::cout << e.code().message() << std::endl;
+     auto url = skyr::url("http://sub.example.إختبار:8090/\xcf\x80?a=1&c=2&b=\xe2\x80\x8d\xf0\x9f\x8c\x88");
+
+     // Using std::format support
+     std::println("Scheme:   {:s}", url);
+     std::println("Domain?   {}", url.is_domain());
+     std::println("Domain:   {:h}", url);    // Encoded (punycode)
+     std::println("Domain:   {:hd}", url);   // Decoded (unicode)
+     std::println("Port:     {:p}", url);
+     std::println("Pathname: {:Pd}", url);   // Decoded pathname
+
+     std::println("\nSearch parameters:");
+     const auto &search = url.search_parameters();
+     for (const auto &[key, value] : search) {
+       std::println("  key: {}, value = {}", key, value);
      }
    }
 
@@ -85,12 +76,12 @@ and standard library.
 
    # CMakeLists.txt
 
+   cmake_minimum_required(VERSION 3.21)
    project(my_project)
 
-   find_package(tl-expected CONFIG REQUIRED)
    find_package(skyr-url CONFIG REQUIRED)
 
-   set(CMAKE_CXX_STANDARD 17)
+   set(CMAKE_CXX_STANDARD 23)
 
    add_executable(url_test url_test.cpp)
    target_link_libraries(url_test PRIVATE skyr::skyr-url)
@@ -112,13 +103,13 @@ and standard library.
 Design objectives
 ^^^^^^^^^^^^^^^^^
 
-* Uses modern C++17 features
-* Cross-platform
-* Easy to use and read
-* Compliant to the the WhatWG URL standard
-* Works naturally with Unicode strings
-* Uses modern CMake and is available as a dependency using a package
-  manager
+* Uses modern C++23 features (``std::expected``, ``std::format``, ``std::ranges``)
+* Header-only library with zero external dependencies
+* Cross-platform (Linux, macOS, Windows)
+* Easy to use and read with immutable, functional-style API
+* Compliant with the WhatWG URL specification
+* Works naturally with Unicode strings (IDNA/Punycode support)
+* Uses modern CMake and is available via vcpkg
 
 Documentation
 -------------

docs/index.rst

@@ -20,15 +20,15 @@ Example
 .. code-block:: c++
 
    #include <skyr/url.hpp>
-   #include <iostream>
+   #include <print>
    #include <cassert>
 
    int main() {
      using namespace skyr::literals;
 
      auto url = "http://[1080:0:0:0:8:800:200C:417A]:8090/"_url;
      assert(url.is_ipv6_address());
-     std::cout << "IPv6 Host: " << urlhostname() << std::endl;
+     std::println("IPv6 Host: {}", url.hostname());
    }
 
 API

docs/network.rst

@@ -22,13 +22,13 @@ Example
 
    #include <skyr/url.hpp>
    #include <skyr/percent_encoding/percent_decode.hpp>
-   #include <iostream>
+   #include <print>
 
    int main() {
      using namespace skyr::literals;
 
      auto url = "http://www.example.org/\xcf\x80/"_url;
-     std::cout << skyr::percent_decode<std::string>(url.pathname()).value() << std::endl;
+     std::println(skyr::percent_decode<std::string>(url.pathname()).value());
    }
 
 API

docs/percent_encoding.rst

@@ -5,8 +5,17 @@ Description
 -----------
 
 The ``skyr::url`` class parses a URL in the constructor and provides
-a rich interface to access and process the URL components. The
-``skyr::url`` constructor throws a ``skyr::url_parse_error`` on failure.
+a rich interface to access and process the URL components. The library
+uses C++23 ``std::expected`` for error handling, providing type-safe
+error propagation without exceptions.
+
+Key features:
+
+* Immutable URL transformations with ``with_*`` methods
+* URL sanitization methods to remove credentials, fragments, and query parameters
+* Custom ``std::format`` support with format specifiers for URL components
+* Percent encoding and decoding
+* IDNA and Punycode for internationalized domain names
 
 Headers
 -------
@@ -15,29 +24,67 @@ Headers
 
     #include <skyr/url.hpp>
 
-Example
--------
+Basic Example
+-------------
 
 .. code-block:: c++
 
     #include <skyr/url.hpp>
-    #include <iostream>
+    #include <print>
 
     int main() {
-      using namespace skyr::literals;
+      auto url = skyr::url("http://example.com/path?query=1");
 
-      try {
-        auto url = "http://example.com/"_url;
+      std::println("Scheme:   {}", url.scheme());
+      std::println("Hostname: {}", url.hostname());
+      std::println("Pathname: {}", url.pathname());
+      std::println("Search:   {}", url.search());
+    }
 
-        std::cout << "Protocol: " << url.protocol() << std::endl;
-        std::cout << "Hostname: " << url.hostname() << std::endl;
-        std::cout << "Pathname: " << url.pathname() << std::endl;
-      }
-      catch (const skyr::url_parse_error &e) {
-        std::cout << e.code().message() << std::endl;
+Immutable Transformations
+--------------------------
+
+.. code-block:: c++
+
+    #include <skyr/url.hpp>
+    #include <print>
+
+    int main() {
+      auto dev_url = skyr::url("http://localhost:3000/api/v1/users");
+
+      // Transform development URL to production
+      auto prod_url = dev_url.with_scheme("https")
+                          .and_then([](auto&& u) { return u.with_hostname("api.example.com"); })
+                          .and_then([](auto&& u) { return u.with_port(""); })
+                          .and_then([](auto&& u) { return u.with_pathname("/api/v2/users"); });
+
+      if (prod_url) {
+        std::println("Production: {}", prod_url->href());
       }
     }
 
+URL Sanitization
+----------------
+
+.. code-block:: c++
+
+    #include <skyr/url.hpp>
+    #include <print>
+
+    int main() {
+      auto url = skyr::url("http://user:pass@example.com/path?debug=true&id=123#section");
+
+      // Remove credentials and fragment
+      auto safe_url = url.sanitize();
+      std::println("{}", safe_url.href());
+      // Output: http://example.com/path?debug=true&id=123
+
+      // Chain operations to remove specific parameters
+      auto clean_url = url.sanitize().without_params({"debug"});
+      std::println("{}", clean_url.href());
+      // Output: http://example.com/path?id=123
+    }
+
 API
 ---
 

docs/url.rst

@@ -60,7 +60,7 @@ class host {
   }
 
   /// Constructor
-  /// \param hsost An empty host
+  /// \param host An empty host
   constexpr explicit host(empty_host host) : host_(host) {
   }