Modify documentation (olp-cpp-sdk-core/client) (#610)

Relates to: OLPEDGE-1441

Signed-off-by: Halyna Dumych <[email protected]>

Author: HalynaDumych

olp-cpp-sdk-core/include/olp/core/client/ApiError.h

@@ -62,8 +62,8 @@ class CORE_API ApiError {
   /**
    * @brief Creates the `ApiError` instance with the HTTP status code.
    *
-   * Represents the server status. Evaluates the HTTP status code and sets the
-   * `error_code_` and `is_retriable_ flag` parameters . You can call this
+   * Represents the server status. Evaluates the HTTP status code and sets
+   * the `error_code_` and `is_retriable_ flag` parameters. You can call this
    * constructor using the HTTP status code and error text message.
    *
    * @param http_status_code The HTTP status code returned by the server.
@@ -76,28 +76,30 @@ class CORE_API ApiError {
         is_retryable_(http::HttpStatusCode::IsRetryable(http_status_code)) {}
 
   /**
-   * Gets the error code.
+   * @brief Gets the error code.
    *
    * @return The code associated with the error.
    */
   inline ErrorCode GetErrorCode() const { return error_code_; }
 
   /**
-   * Gets the HTTP status code.
+   * @brief Gets the HTTP status code.
    *
    * @return The HTTP status code.
    */
   inline int GetHttpStatusCode() const { return http_status_code_; }
 
   /**
-   * Gets the error message.
+   * @brief Gets the error message.
    *
    * @return The error message associated with the error.
    */
   inline const std::string& GetMessage() const { return message_; }
 
   /**
-   * Returns true if a request can be retried for this error.
+   * @brief Checks if the request can be retried for this error.
+   *
+   * @return True if the request can be retried for this error; false otherwise.
    */
   inline bool ShouldRetry() const { return is_retryable_; }
 

olp-cpp-sdk-core/include/olp/core/client/ApiNoResult.h

@@ -23,8 +23,9 @@ namespace olp {
 namespace client {
 
 /**
- * Used when an ApiResponse does not contain result data. E.g. a HTTP 200
- * response with no response body.
+ * @brief Used when `ApiResponse` does not contain result data.
+ *
+ * Example: the HTTP 200 response with no response body.
  */
 class ApiNoResult {};
 

olp-cpp-sdk-core/include/olp/core/client/ApiResponse.h

@@ -28,24 +28,34 @@ namespace olp {
 namespace client {
 
 /**
- * Represents a request outcome.
+ * @brief Represents a request outcome.
  *
  * Contains a successful result or failure error. Before you try to access
- * the result of the error, check the request outcome.
+ * the error result, check the request outcome.
  *
  * @tparam Result The result type.
  * @tparam Error The error type.
  */
 template <typename Result, typename Error>
 class ApiResponse {
  public:
+  /**
+   * @brief The type of result.
+   */
   using ResultType = Result;
+  /**
+   * @brief The type of error.
+   */
   using ErrorType = Error;
 
   ApiResponse() = default;
 
   /**
-   * @brief ApiResponse Constructor for moving a successfully executed request.
+   * @brief Creates the `ApiResponse` instance.
+   *
+   * Used for moving the successfully executed request.
+   *
+   * @param result The `ResultType` instance.
    */
   ApiResponse(ResultType result) : result_(std::move(result)), success_(true) {}
 
@@ -57,35 +67,39 @@ class ApiResponse {
   ApiResponse(const ErrorType& error) : error_(error), success_(false) {}
 
   /**
-   * @brief ApiResponse Copy constructor.
+   * @brief Creates the `ApiResponse` instance that is a copy of the `r`
+   * parameter.
+   *
+   * @param r The `ApiResponse` instance from which the response is copied.
    */
   ApiResponse(const ApiResponse& r)
       : result_(r.result_), error_(r.error_), success_(r.success_) {}
 
   /**
-   * @brief IsSuccessful Gets the status of the request attempt.
-   * @return True is request successfully completed.
+   * @brief Checks the status of the request attempt.
+   *
+   * @return True if the request is successfully completed; false otherwise.
    */
   inline bool IsSuccessful() const { return success_; }
 
   /**
-   * @brief GetResult Gets the result for a succcessfully executed request
-   * @return A valid Result if IsSuccessful() returns true. Undefined,
-   * otherwise.
+   * @brief Gets the result of the successfully executed request.
+   *
+   * @return The result instance.
    */
   inline const ResultType& GetResult() const { return result_; }
 
   /**
-   * @brief MoveResult Moves the result for a succcessfully executed request
-   * @return A valid Result if IsSuccessful() returns true. Undefined,
-   * otherwise.
+   * @brief Moves the result of the successfully executed request.
+   *
+   * @return The forwarding reference to the result instance.
    */
   inline ResultType&& MoveResult() { return std::move(result_); }
 
   /**
-   * @brief GetError Gets the error for an unsucccessful request attempt.
-   * @return A valid Error if IsSuccessful() returns false. Undefined,
-   * otherwise.
+   * @brief Gets the error of the unsuccessful request attempt.
+   *
+   * @return The result instance.
    */
   inline const ErrorType& GetError() const { return error_; }
 
@@ -96,15 +110,17 @@ class ApiResponse {
 };
 
 /**
- * @brief A wrapper template that you can use to cancel the request or wait for
+ * @brief A wrapper template that you can use to cancel a request or wait for
  * it to finalize.
  *
  * @tparam T The result type.
  */
 template <typename T>
 class CancellableFuture {
  public:
-  /// The typedef for the sharable promise.
+  /**
+   * @brief The sharable promise type.
+   */
   using PromisePtr = std::shared_ptr<std::promise<T>>;
 
   /**
@@ -118,7 +134,7 @@ class CancellableFuture {
       : cancel_token_(cancel_token), promise_(std::move(promise)) {}
 
   /**
-   * @brief Gets the `CancellationToken` reference used to cancell the ongoing
+   * @brief Gets the `CancellationToken` reference used to cancel the ongoing
    * operation.
    *
    * @return The constant reference to the `CancellationToken` instance.

olp-cpp-sdk-core/include/olp/core/client/CancellationContext.h

@@ -30,60 +30,84 @@ namespace olp {
 namespace client {
 
 /**
- * @brief Wrapper which manages cancellation state for any asynchronous
- * operations in a thread safe way.
- * All public APIs are thread safe.
+ * @brief A wrapper that manages the cancellation state of an asynchronous
+ * operation in a thread-safe way.
+ *
+ * All public APIs are thread-safe.
+ *
  * This class is both movable and copyable.
  */
 class CORE_API CancellationContext {
  public:
+  /**
+   * @brief The type alias of the operation function.
+   */
   using ExecuteFuncType = std::function<CancellationToken()>;
+  /**
+   * @brief The type alias of the cancel function.
+   */
   using CancelFuncType = std::function<void()>;
 
   CancellationContext();
 
   /**
-   * @brief Execute a given cancellable code block if the operation has not yet
-   * been cancelled. Otherwise, execute a custom cancellation function.
-   * @param execute_fn A function to execute if this operation is not yet
-   * cancelled. This function should return a CancellationToken which
-   * CancellationContext will propogate a cancel request to.
-   * @param cancel_fn A function which will be called if this operation is
-   * already cancelled.
-   * @return true in case of successfull execution, false in case context was
+   * @brief Executes the given cancellable code block if the operation is not
+   * cancelled.
+   *
+   * Otherwise, executes the custom cancellation function.
+   *
+   * @param execute_fn The function that should be executed if this operation is
+   * not cancelled. This function should return `CancellationToken` for which
+   * `CancellationContext` propagates a cancel request.
+   * @param cancel_fn The function that is called if this operation is
+   * cancelled.
+   *
+   * @return True if the execution is successful; false if the context was
    * cancelled.
-   * @deprecated Will be removed once TaskScheduler will be used.
+   *
+   * @deprecated Will be removed. Use `TaskScheduler` instead.
    */
   bool ExecuteOrCancelled(const ExecuteFuncType& execute_fn,
                           const CancelFuncType& cancel_fn = nullptr);
 
   /**
-   * @brief Allows the user to cancel an ongoing operation in a threadsafe way.
+   * @brief Cancels the ongoing operation in a thread-safe way.
    */
   void CancelOperation();
 
   /**
-   * @brief Check if this context was cancelled.
-   * @return `true` on context cancelled, `false` otherwise.
+   * @brief Checks whether this context is cancelled.
+   *
+   * @return True if the context is cancelled; false otherwise.
    */
   bool IsCancelled() const;
 
  private:
   /**
-   * @brief Implementation to be able to shared a instance of
-   * CancellationContext.
+   * @brief An implementation used to shared the `CancellationContext` instance.
    */
   struct CancellationContextImpl {
-    /// Mutex lock to protect from concurrent read/write.
+    /**
+     * @brief The mutex lock used to protect the `CancellationContext` object
+     * from the concurrent read and write operations.
+     */
     mutable std::recursive_mutex mutex_;
-    /// Sub operation context return from ExecuteOrCancelled() execute_fn.
-    /// @deprecated This will be removed once TaskScheduler is used.
+    /**
+     * @brief The suboperation context returned from `execute_fn` of
+     * `ExecuteOrCancelled()`.
+     *
+     * @deprecated Will be removed. Use `TaskScheduler` instead.
+     */
     CancellationToken sub_operation_cancel_token_{};
-    /// Flag that will be set to `true` on CancelOperation().
+    /**
+     * @brief The flag that is set to `true` for `CancelOperation()`.
+     */
     bool is_cancelled_{false};
   };
 
-  /// Shared implementation.
+  /**
+   * @brief The shared implementation.
+   */
   std::shared_ptr<CancellationContextImpl> impl_;
 };
 

olp-cpp-sdk-core/include/olp/core/client/CancellationToken.h

@@ -28,19 +28,21 @@ namespace olp {
 namespace client {
 
 /**
- * @brief Cancels service requests
+ * @brief Cancels service requests.
  */
 class CORE_API CancellationToken {
  public:
-  /// The alias for the cancellation function.
+  /**
+   * @brief The alias for the cancellation function.
+   */
   using CancelFuncType = std::function<void()>;
 
   CancellationToken() = default;
 
   /**
    * @brief Creates the `CancellationToken` instance.
    *
-   * @param func The operation that should be used to cancel the ongoing.
+   * @param func The operation that should be used to cancel the ongoing
    * operation.
    */
   CancellationToken(CancelFuncType func);

olp-cpp-sdk-core/include/olp/core/client/Condition.h

@@ -29,32 +29,35 @@ namespace olp {
 namespace client {
 
 /**
- * @brief The Condition helper class allows to wait until the notification is
- * called by a task or cancellation is performed by the user.
+ * @brief A helper class that allows one thread to call and wait for a
+ * notification in the other thread.
  */
 class Condition final {
  public:
   Condition() = default;
 
   /**
-   * @brief Should be called by task's callback to notify \c Wait to unblock the
-   * routine.
+   * @brief Called by the task callback to notify `Wait` to unblock
+   * the routine.
    */
   void Notify() {
     std::unique_lock<std::mutex> lock(mutex_);
     signaled_ = true;
 
-    // Condition should be under the lock in order to not run into the data
-    // race, which might occur when spurious wakeup happens in the other
-    // thread while waiting for the condition's signal.
+    // Condition should be under the lock not to run into the data
+    // race that might occur when a spurious wakeup happens in the other
+    // thread while waiting for the condition signal.
     condition_.notify_one();
   }
 
   /**
-   * @brief Waits a task for a \c Notify or \c CancellationContext to be
-   * cancelled by the user.
-   * @param timeout milliseconds to wait on condition
-   * @return True on notified wake, False on timeout
+   * @brief Waits for the `Notify` function.
+   *
+   * @param timeout The time (in milliseconds) during which the `Wait`
+   * function waits for the notification.
+   *
+   * @return True if the notification is returned before the timeout; false
+   * otherwise.
    */
   bool Wait(std::chrono::milliseconds timeout = std::chrono::seconds(60)) {
     std::unique_lock<std::mutex> lock(mutex_);

olp-cpp-sdk-core/include/olp/core/client/ErrorCode.h

@@ -48,7 +48,7 @@ enum class ErrorCode {
   RequestTimeout,
 
   /**
-   * Internal server failure.
+   * An internal server failure.
    */
   InternalFailure,