add doxygen

Author: GaspardKirira

include/vix/sync/Operation.hpp

@@ -3,8 +3,10 @@
  *  @file Operation.hpp
  *  @author Gaspard Kirira
  *
- *  Copyright 2025, Gaspard Kirira.  All rights reserved.
+ *  Copyright 2025, Gaspard Kirira.
+ *  All rights reserved.
  *  https://github.com/vixcpp/vix
+ *
  *  Use of this source code is governed by a MIT license
  *  that can be found in the License file.
  *
@@ -21,41 +23,145 @@
 
 namespace vix::sync
 {
-
-  enum class OperationStatus : uint8_t
+  /**
+   * @brief Lifecycle status of a sync operation.
+   *
+   * OperationStatus represents the durable state of an operation
+   * as it flows through the sync pipeline.
+   */
+  enum class OperationStatus : std::uint8_t
   {
+    /**
+     * @brief Operation is persisted and waiting to be processed.
+     */
     Pending = 0,
+
+    /**
+     * @brief Operation has been claimed and is currently being processed.
+     */
     InFlight,
+
+    /**
+     * @brief Operation completed successfully.
+     */
     Done,
+
+    /**
+     * @brief Operation failed but may be retried.
+     */
     Failed,
+
+    /**
+     * @brief Operation failed permanently and will not be retried.
+     */
     PermanentFailed
   };
 
+  /**
+   * @brief Durable representation of a single sync operation.
+   *
+   * Operation is the core unit stored in the Outbox and WAL. It is designed
+   * to be:
+   * - immutable in intent (what to do)
+   * - mutable in state (status, attempts, timestamps)
+   *
+   * The operation lifecycle is fully driven by durable state transitions,
+   * enabling crash-safe retries and deterministic recovery.
+   */
   struct Operation
   {
+    /**
+     * @brief Unique identifier of the operation.
+     */
     std::string id;
+
+    /**
+     * @brief Logical kind or type of operation.
+     *
+     * Examples: "http.request", "p2p.message", "db.mutation".
+     */
     std::string kind;
+
+    /**
+     * @brief Target of the operation.
+     *
+     * Examples: URL, peer id, resource name.
+     */
     std::string target;
+
+    /**
+     * @brief Opaque payload associated with the operation.
+     */
     std::string payload;
+
+    /**
+     * @brief Idempotency key used to deduplicate retries.
+     */
     std::string idempotency_key;
+
+    /**
+     * @brief Creation timestamp in milliseconds.
+     */
     std::int64_t created_at_ms{0};
+
+    /**
+     * @brief Last update timestamp in milliseconds.
+     */
     std::int64_t updated_at_ms{0};
+
+    /**
+     * @brief Number of delivery attempts so far.
+     */
     std::uint32_t attempt{0};
+
+    /**
+     * @brief Next time when the operation becomes eligible for retry.
+     */
     std::int64_t next_retry_at_ms{0};
+
+    /**
+     * @brief Current lifecycle status.
+     */
     OperationStatus status{OperationStatus::Pending};
+
+    /**
+     * @brief Last error message, if any.
+     */
     std::string last_error;
 
+    /**
+     * @brief Check whether the operation is completed.
+     */
     bool is_done() const noexcept { return status == OperationStatus::Done; }
+
+    /**
+     * @brief Check whether the operation is pending.
+     */
     bool is_pending() const noexcept { return status == OperationStatus::Pending; }
+
+    /**
+     * @brief Check whether the operation is failed (retryable).
+     */
     bool is_failed() const noexcept { return status == OperationStatus::Failed; }
 
+    /**
+     * @brief Mark the operation as failed.
+     *
+     * @param err Error message.
+     * @param now_ms Current time in milliseconds.
+     */
     void fail(std::string err, std::int64_t now_ms)
     {
       last_error = std::move(err);
       status = OperationStatus::Failed;
       updated_at_ms = now_ms;
     }
 
+    /**
+     * @brief Mark the operation as successfully completed.
+     *
+     * @param now_ms Completion time in milliseconds.
+     */
     void done(std::int64_t now_ms)
     {
       status = OperationStatus::Done;
@@ -66,4 +172,4 @@ namespace vix::sync
 
 } // namespace vix::sync
 
-#endif
+#endif // VIX_SYNC_OPERATION_HPP

include/vix/sync/RetryPolicy.hpp

@@ -3,8 +3,10 @@
  *  @file RetryPolicy.hpp
  *  @author Gaspard Kirira
  *
- *  Copyright 2025, Gaspard Kirira.  All rights reserved.
+ *  Copyright 2025, Gaspard Kirira.
+ *  All rights reserved.
  *  https://github.com/vixcpp/vix
+ *
  *  Use of this source code is governed by a MIT license
  *  that can be found in the License file.
  *
@@ -14,27 +16,84 @@
 #ifndef VIX_SYNC_RETRY_POLICY_HPP
 #define VIX_SYNC_RETRY_POLICY_HPP
 
-#include <cstdint>
 #include <algorithm>
+#include <cstdint>
 
 namespace vix::sync
 {
-
+  /**
+   * @brief Exponential backoff retry policy.
+   *
+   * RetryPolicy defines how failed operations are retried over time.
+   * It supports:
+   * - a maximum number of attempts
+   * - exponential backoff based on a base delay and factor
+   * - clamping to a maximum delay
+   * - optional jitter (documented here, applied by caller if needed)
+   *
+   * The policy itself is deterministic and side-effect free, making it
+   * suitable for durable systems where retry timing must be recomputable
+   * during recovery.
+   */
   struct RetryPolicy
   {
+    /**
+     * @brief Maximum number of retry attempts.
+     *
+     * Once attempt >= max_attempts, no further retries are allowed.
+     */
     std::uint32_t max_attempts{8};
-    std::int64_t base_delay_ms{500};   // 0.5s
+
+    /**
+     * @brief Base delay in milliseconds for the first retry.
+     */
+    std::int64_t base_delay_ms{500}; // 0.5s
+
+    /**
+     * @brief Maximum delay in milliseconds between retries.
+     */
     std::int64_t max_delay_ms{30'000}; // 30s
-    // Exponential factor: delay = base * (2^attempt)
+
+    /**
+     * @brief Exponential backoff factor.
+     *
+     * Delay grows as: base_delay_ms * (factor ^ attempt).
+     */
     double factor{2.0};
-    // 0.0 = none, 0.2 = +/-20%
+
+    /**
+     * @brief Jitter ratio applied by higher-level logic.
+     *
+     * Expressed as a fraction:
+     * - 0.0  = no jitter
+     * - 0.2  = +/-20% randomization window
+     *
+     * @note This policy does not apply jitter directly. It exposes the
+     * parameter so callers (e.g. Outbox or Engine) can apply randomness
+     * in a controlled manner.
+     */
     double jitter_ratio{0.2};
 
+    /**
+     * @brief Check whether another retry is allowed.
+     *
+     * @param attempt Current attempt count (0-based).
+     * @return true if another retry may be scheduled.
+     */
     bool can_retry(std::uint32_t attempt) const noexcept
     {
       return attempt < max_attempts;
     }
 
+    /**
+     * @brief Compute the retry delay for a given attempt.
+     *
+     * The delay grows exponentially and is clamped between
+     * base_delay_ms and max_delay_ms.
+     *
+     * @param attempt Current attempt count (0-based).
+     * @return Delay in milliseconds before the next retry.
+     */
     std::int64_t compute_delay_ms(std::uint32_t attempt) const noexcept
     {
       // attempt: 0,1,2,... (0 => base)
@@ -49,4 +108,4 @@ namespace vix::sync
 
 } // namespace vix::sync
 
-#endif
+#endif // VIX_SYNC_RETRY_POLICY_HPP