add doxygen

Author: GaspardKirira

include/vix/async/core/cancel.hpp

@@ -3,8 +3,10 @@
  *  @file cancel.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,72 +23,163 @@
 
 namespace vix::async::core
 {
+  /**
+   * @brief Shared cancellation state.
+   *
+   * cancel_state holds the atomic cancellation flag shared between
+   * a cancel_source and all associated cancel_token instances.
+   *
+   * This object is reference-counted and designed to be safely
+   * accessed concurrently from multiple threads.
+   */
   class cancel_state
   {
   public:
+    /**
+     * @brief Request cancellation.
+     *
+     * Sets the internal cancellation flag. This operation is
+     * thread-safe and may be called multiple times.
+     */
     void request_cancel() noexcept
     {
       cancelled_.store(true, std::memory_order_release);
     }
 
+    /**
+     * @brief Check whether cancellation was requested.
+     *
+     * @return true if cancellation has been requested, false otherwise.
+     */
     bool is_cancelled() const noexcept
     {
       return cancelled_.load(std::memory_order_acquire);
     }
 
   private:
+    /**
+     * @brief Atomic cancellation flag.
+     */
     std::atomic<bool> cancelled_{false};
   };
 
+  /**
+   * @brief Lightweight cancellation observer.
+   *
+   * cancel_token provides a read-only view of a cancellation state.
+   * It does not own the state and cannot request cancellation itself.
+   *
+   * Tokens are cheap to copy and may be safely passed across threads.
+   */
   class cancel_token
   {
   public:
+    /**
+     * @brief Construct an empty (non-cancelable) token.
+     */
     cancel_token() = default;
 
+    /**
+     * @brief Construct a token bound to a cancellation state.
+     *
+     * @param st Shared cancellation state.
+     */
     explicit cancel_token(std::shared_ptr<cancel_state> st) noexcept
         : st_(std::move(st)) {}
 
-    bool can_cancel() const noexcept { return static_cast<bool>(st_); }
+    /**
+     * @brief Check whether this token is associated with a cancel source.
+     *
+     * @return true if the token can observe cancellation, false otherwise.
+     */
+    bool can_cancel() const noexcept
+    {
+      return static_cast<bool>(st_);
+    }
 
+    /**
+     * @brief Check whether cancellation has been requested.
+     *
+     * @return true if cancellation was requested, false otherwise.
+     */
     bool is_cancelled() const noexcept
     {
       return st_ ? st_->is_cancelled() : false;
     }
 
   private:
+    /**
+     * @brief Shared cancellation state.
+     */
     std::shared_ptr<cancel_state> st_{};
   };
 
+  /**
+   * @brief Cancellation source and owner.
+   *
+   * cancel_source owns the cancellation state and is responsible
+   * for issuing cancellation requests. All tokens produced by
+   * this source observe the same cancellation state.
+   */
   class cancel_source
   {
   public:
-    cancel_source() : st_(std::make_shared<cancel_state>()) {}
-
+    /**
+     * @brief Construct a new cancellation source.
+     *
+     * The associated cancellation state starts in a non-cancelled state.
+     */
+    cancel_source()
+        : st_(std::make_shared<cancel_state>()) {}
+
+    /**
+     * @brief Obtain a cancellation token linked to this source.
+     *
+     * @return A cancel_token observing this source.
+     */
     cancel_token token() const noexcept
     {
       return cancel_token{st_};
     }
 
+    /**
+     * @brief Request cancellation.
+     *
+     * Signals cancellation to all associated tokens.
+     */
     void request_cancel() noexcept
     {
       if (st_)
         st_->request_cancel();
     }
 
+    /**
+     * @brief Check whether cancellation has been requested.
+     *
+     * @return true if cancellation was requested, false otherwise.
+     */
     bool is_cancelled() const noexcept
     {
       return st_ ? st_->is_cancelled() : false;
     }
 
   private:
+    /**
+     * @brief Shared cancellation state.
+     */
     std::shared_ptr<cancel_state> st_;
   };
 
+  /**
+   * @brief Standard error code for cancellation.
+   *
+   * @return std::error_code representing a cancelled operation.
+   */
   inline std::error_code cancelled_ec() noexcept
   {
     return make_error_code(errc::canceled);
   }
 
 } // namespace vix::async::core
 
-#endif
+#endif // VIX_ASYNC_CANCEL_HPP

include/vix/async/core/error.hpp

@@ -3,8 +3,10 @@
  *  @file error.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,37 +23,108 @@
 namespace vix::async::core
 {
 
+  /**
+   * @brief Error codes for the async core subsystem.
+   *
+   * This enumeration defines all error conditions that can be
+   * reported by the asynchronous runtime, scheduler, thread pool,
+   * timers, and cancellation mechanisms.
+   *
+   * Values are intentionally compact and stable to allow efficient
+   * propagation through std::error_code.
+   */
   enum class errc : std::uint8_t
   {
+    /**
+     * @brief No error.
+     */
     ok = 0,
 
     // Generic
+
+    /**
+     * @brief Invalid argument passed to an API.
+     */
     invalid_argument,
+
+    /**
+     * @brief Operation cannot complete yet.
+     */
     not_ready,
+
+    /**
+     * @brief Operation timed out.
+     */
     timeout,
+
+    /**
+     * @brief Operation was canceled.
+     */
     canceled,
+
+    /**
+     * @brief Resource or channel was closed.
+     */
     closed,
+
+    /**
+     * @brief Capacity or numeric overflow.
+     */
     overflow,
 
     // Scheduler / runtime
+
+    /**
+     * @brief Runtime or scheduler has been stopped.
+     */
     stopped,
+
+    /**
+     * @brief Internal task queue is full.
+     */
     queue_full,
 
     // Thread pool
+
+    /**
+     * @brief Task submission was rejected.
+     */
     rejected,
 
     // Signals / timers
+
+    /**
+     * @brief Operation is not supported on this platform.
+     */
     not_supported
   };
 
+  /**
+   * @brief Error category for async core errors.
+   *
+   * Provides human-readable messages and categorization for
+   * errc values. This category integrates with std::error_code
+   * and std::error_condition.
+   */
   class error_category final : public std::error_category
   {
   public:
+    /**
+     * @brief Return the name of the error category.
+     *
+     * @return Category name ("async").
+     */
     const char *name() const noexcept override
     {
       return "async";
     }
 
+    /**
+     * @brief Return a descriptive message for an error code.
+     *
+     * @param c Integer value of the error code.
+     * @return Human-readable error message.
+     */
     std::string message(int c) const override
     {
       switch (static_cast<errc>(c))
@@ -84,25 +157,39 @@ namespace vix::async::core
     }
   };
 
+  /**
+   * @brief Access the singleton async error category.
+   *
+   * @return Reference to the async error category.
+   */
   inline const std::error_category &category() noexcept
   {
     static error_category cat;
     return cat;
   }
 
+  /**
+   * @brief Create a std::error_code from an async error code.
+   *
+   * @param e Async error code.
+   * @return Corresponding std::error_code.
+   */
   inline std::error_code make_error_code(errc e) noexcept
   {
     return {static_cast<int>(e), category()};
   }
 
-} // namespace async::core
+} // namespace vix::async::core
 
 namespace std
 {
+  /**
+   * @brief Enable implicit conversion of errc to std::error_code.
+   */
   template <>
   struct is_error_code_enum<vix::async::core::errc> : true_type
   {
   };
 } // namespace std
 
-#endif
+#endif // VIX_ASYNC_ERROR_HPP