Add doxygen and benchmarck

Author: GaspardKirira

CMakeLists.txt

@@ -176,6 +176,19 @@ if (VIX_TIME_BUILD_EXAMPLES)
   endif()
 endif()
 
+# ======================================================
+# Benchmarks
+# ======================================================
+
+option(VIX_TIME_BUILD_BENCH "Build time module benchmarks" OFF)
+
+if (VIX_TIME_BUILD_BENCH)
+  if (EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/src/bench/CMakeLists.txt")
+    add_subdirectory(src/bench)
+  else()
+    message(WARNING "[time/bench] VIX_TIME_BUILD_BENCH=ON but src/bench/CMakeLists.txt not found, skipping.")
+  endif()
+endif()
 
 # ======================================================
 # Summary

README.md

@@ -20,6 +20,37 @@ fully type-safe, chrono-based, and explicit.
 - 📦 Header-only (v1)
 - 🚫 No hidden allocations, no magic, no dependencies
 
+## Benchmarks
+
+Benchmarks are built using an internal chrono-based harness
+(no external dependencies).
+
+Build:
+```bash
+cmake -S . -B build -DVIX_TIME_BUILD_BENCH=ON
+cmake --build build
+```
+Run:
+
+```bash
+./build/src/bench/vix_time_bench
+```
+
+#### Example results (Linux, x86_64):
+
+- Date.parse("YYYY-MM-DD"): ~170 ns (p50)
+- DateTime.parse ISO-8601: ~1.1 µs (p50)
+- Timestamp.now(): ~65 ns (p50)
+- Date.to_timestamp_utc(): ~240 ns (p50)
+
+### These numbers make vix::time suitable for:
+
+- logging
+- tracing
+- WAL
+- retry / timeout logic
+- scheduling
+
 ---
 
 ## Installation

examples/basic_date.cpp

@@ -12,10 +12,7 @@ using namespace vix::time;
 
 int main()
 {
-  // --------------------------------------------
-  // Date facade (Node.js / Python-like)
-  // --------------------------------------------
-
+  // Date facade
   Date today = Date::now();
   std::cout << "Today (UTC): " << today.to_string() << "\n";
 
@@ -27,21 +24,15 @@ int main()
   std::cout << "Day start (epoch seconds): "
             << day_start.seconds_since_epoch() << "\n";
 
-  // --------------------------------------------
   // DateTime
-  // --------------------------------------------
-
   DateTime now = DateTime::now_utc();
   std::cout << "Now (UTC): " << now.to_string_utc() << "\n";
 
   DateTime parsed_dt = DateTime::parse("2026-02-07T10:30:15Z");
   std::cout << "Parsed datetime: "
             << parsed_dt.to_string_utc() << "\n";
 
-  // --------------------------------------------
   // Timestamp + Duration arithmetic
-  // --------------------------------------------
-
   Timestamp t0 = Timestamp::now();
   Duration wait = Duration::seconds(2);
 
@@ -51,10 +42,7 @@ int main()
   std::cout << "Delta (seconds): "
             << delta.count_seconds() << "\n";
 
-  // --------------------------------------------
   // Steady clock (elapsed time)
-  // --------------------------------------------
-
   auto start = SteadyClock::now_chrono();
   // simulate work
   int sink = 0;

include/vix/time/Clock.hpp

@@ -9,16 +9,8 @@
  * Use of this source code is governed by a MIT license
  * that can be found in the LICENSE file.
  *
- * =====================================================
- * Vix.cpp — Time Module / Clock
- * =====================================================
+ * Vix.cpp
  *
- * Clock utilities for retrieving current time.
- *
- * - System clock: wall time, epoch-based (Timestamp)
- * - Steady clock: monotonic time for measuring durations
- *
- * This module keeps APIs explicit and predictable.
  */
 
 #ifndef VIX_TIME_CLOCK_HPP
@@ -34,10 +26,25 @@ namespace vix::time
   /**
    * @brief System clock helpers (wall time).
    *
-   * Returns epoch-based timestamps (nanoseconds since epoch).
+   * @details
+   * Use this when you need the current real-world time, such as:
+   * - timestamps in logs
+   * - persisted records (files, databases, events)
+   * - user-facing "created_at" / "updated_at"
+   *
+   * The returned value is an epoch-based @ref Timestamp (nanoseconds since epoch).
+   *
+   * @note
+   * Wall time can jump (NTP sync, manual clock change, VM suspend/resume).
+   * For measuring elapsed time, prefer @ref SteadyClock.
    */
   struct SystemClock
   {
+    /**
+     * @brief Get the current wall-clock time as a @ref Timestamp.
+     *
+     * @return Current time (nanoseconds since epoch).
+     */
     static Timestamp now() noexcept
     {
       return Timestamp::now();
@@ -47,19 +54,49 @@ namespace vix::time
   /**
    * @brief Steady/monotonic clock helpers.
    *
-   * Used for measuring elapsed time (timeouts, benchmarks).
-   * Not related to wall time and not convertible to Timestamp.
+   * @details
+   * Use this for measuring elapsed time reliably:
+   * - timeouts
+   * - benchmarks
+   * - profiling durations
+   *
+   * This clock is monotonic and does not track wall time.
+   * It is not convertible to @ref Timestamp.
+   *
+   * @par Beginner example
+   * @code
+   * using vix::time::SteadyClock;
+   *
+   * const auto start = SteadyClock::now_chrono();
+   * // ... work ...
+   * const auto elapsed = SteadyClock::since(start);
+   * @endcode
    */
   class SteadyClock
   {
   public:
+    /// Internal chrono time_point type used by @ref SteadyClock.
     using chrono_tp = std::chrono::time_point<std::chrono::steady_clock, std::chrono::nanoseconds>;
 
+    /**
+     * @brief Get a monotonic time point with nanosecond precision.
+     *
+     * @return Current steady_clock time_point cast to nanoseconds.
+     */
     static chrono_tp now_chrono() noexcept
     {
       return std::chrono::time_point_cast<std::chrono::nanoseconds>(std::chrono::steady_clock::now());
     }
 
+    /**
+     * @brief Compute the elapsed duration since @p start.
+     *
+     * @param start A time point returned by @ref now_chrono.
+     * @return Elapsed time as a @ref Duration.
+     *
+     * @note
+     * Passing a time point from a different clock type is undefined behavior.
+     */
     static Duration since(const chrono_tp &start) noexcept
     {
       const auto delta = now_chrono() - start;

include/vix/time/Date.hpp

@@ -9,17 +9,7 @@
  * Use of this source code is governed by a MIT license
  * that can be found in the LICENSE file.
  *
- * =====================================================
- * Vix.cpp - Time Module / Date
- * =====================================================
- *
- * Ergonomic date facade inspired by Node.js and Python.
- *
- * This type represents a calendar date (year-month-day) without time.
- * It is designed to be:
- * - simple to construct and parse
- * - explicit and predictable
- * - chrono-based
+ * Vix.cpp
  */
 
 #ifndef VIX_TIME_DATE_HPP
@@ -37,16 +27,33 @@
 namespace vix::time
 {
   /**
-   * @brief Calendar date (year-month-day).
+   * @brief Calendar date (year-month-day), without time and without timezone.
+   *
+   * @details
+   * Date is a small value type representing a calendar day.
+   * It does not store timezone data.
+   *
+   * Converting a Date to a @ref Timestamp is done in UTC at 00:00:00.
+   *
+   * This type is designed to stay friendly for beginners (simple fields, simple parsing)
+   * while remaining useful for advanced users (chrono-based validation and conversion).
    *
-   * This is a lightweight value type. It does not store timezone data.
-   * All conversions to Timestamp are performed in UTC at 00:00:00.
+   * @par Beginner example
+   * @code
+   * using vix::time::Date;
+   *
+   * Date d = Date::parse("2026-02-07");
+   * if (!d.is_valid())
+   *   return;
+   *
+   * std::cout << d.to_string() << "\n";
+   * @endcode
    */
   class Date
   {
   public:
     /**
-     * @brief Construct a default date (1970-01-01).
+     * @brief Construct the default date: 1970-01-01.
      */
     constexpr Date() noexcept
         : year_(1970), month_(1), day_(1)
@@ -56,27 +63,36 @@ namespace vix::time
     /**
      * @brief Construct a date from explicit fields.
      *
-     * @param year  Full year (e.g. 2026)
-     * @param month Month in [1..12]
-     * @param day   Day in [1..31] (calendar validation is done by is_valid()).
+     * @param year  Full year (e.g. 2026).
+     * @param month Month in [1..12] (range is checked by @ref is_valid).
+     * @param day   Day in [1..31] (calendar validation is checked by @ref is_valid).
+     *
+     * @note
+     * This constructor does not validate the calendar day. Use @ref is_valid
+     * to check validity.
      */
     constexpr Date(int year, int month, int day) noexcept
         : year_(year), month_(month), day_(day)
     {
     }
 
     /**
-     * @brief Current date (UTC).
+     * @brief Current date in UTC.
+     *
+     * @return Today's date in UTC.
      *
-     * Alias of today().
+     * @note
+     * This is an alias of @ref today.
      */
     static Date now() noexcept
     {
       return today();
     }
 
     /**
-     * @brief Current date (UTC).
+     * @brief Current date in UTC.
+     *
+     * @return Today's date in UTC.
      */
     static Date today() noexcept
     {
@@ -92,11 +108,17 @@ namespace vix::time
     }
 
     /**
-     * @brief Parse date from "YYYY-MM-DD".
+     * @brief Parse a date from "YYYY-MM-DD".
      *
-     * On parse failure, returns the default date (1970-01-01).
+     * @details
+     * On parse failure, this returns the default date (1970-01-01).
      *
      * @param s Input string view.
+     * @return Parsed date, or default date on failure.
+     *
+     * @note
+     * Parsing succeeds even if the date is not a valid calendar day.
+     * Use @ref is_valid to validate.
      */
     static Date parse(std::string_view s) noexcept
     {
@@ -105,30 +127,34 @@ namespace vix::time
       int d = 0;
 
       if (!vix::time::parse::parse_ymd(s, y, m, d))
-      {
         return Date();
-      }
 
       return Date(y, m, d);
     }
 
     /**
-     * @brief Return the year.
+     * @brief Get the year component.
      */
     constexpr int year() const noexcept { return year_; }
 
     /**
-     * @brief Return the month in [1..12] (as stored).
+     * @brief Get the month component (as stored).
+     *
+     * @return Month in [1..12] if valid.
      */
     constexpr int month() const noexcept { return month_; }
 
     /**
-     * @brief Return the day in [1..31] (as stored).
+     * @brief Get the day component (as stored).
+     *
+     * @return Day in [1..31] if valid.
      */
     constexpr int day() const noexcept { return day_; }
 
     /**
-     * @brief Check if the date is a valid calendar day.
+     * @brief Check if this date is a valid calendar day.
+     *
+     * @return True if year-month-day forms a valid date, false otherwise.
      */
     constexpr bool is_valid() const noexcept
     {
@@ -145,7 +171,11 @@ namespace vix::time
     /**
      * @brief Convert this date to a UTC timestamp at 00:00:00.
      *
-     * If the date is invalid, returns Timestamp().
+     * @details
+     * If the date is invalid (@ref is_valid is false), this returns a default
+     * constructed @ref Timestamp.
+     *
+     * @return UTC timestamp at midnight for this date, or default Timestamp on invalid date.
      */
     Timestamp to_timestamp_utc() const noexcept
     {
@@ -167,6 +197,11 @@ namespace vix::time
 
     /**
      * @brief Format as "YYYY-MM-DD".
+     *
+     * @return String representation of the date.
+     *
+     * @note
+     * This does not validate the date. It prints stored fields.
      */
     std::string to_string() const
     {
@@ -195,7 +230,7 @@ namespace vix::time
     }
 
     /**
-     * @brief Strict weak ordering.
+     * @brief Strict weak ordering (lexicographic by year, month, day).
      */
     friend constexpr bool operator<(const Date &a, const Date &b) noexcept
     {