Review the dataservice-write API docs (#1280)

The API documentation should be aligned and follow the Doxygen
documentation rules.

Relates-To: OLPEDGE-855
Signed-off-by: Halyna Dumych <[email protected]>

Author: HalynaDumych

olp-cpp-sdk-dataservice-write/include/olp/dataservice/write/IndexLayerClient.h

@@ -56,95 +56,99 @@ using UpdateIndexResponse =
     client::ApiResponse<client::ApiNoResult, client::ApiError>;
 using UpdateIndexCallback = std::function<void(UpdateIndexResponse response)>;
 
-/**
- * @brief Client that is responsible for writing data to
- * a HERE platform index layer.
- *
- */
+/// Publishes data to an index layer.
 class DATASERVICE_WRITE_API IndexLayerClient {
  public:
   /**
    * @brief Creates the `IndexLayerClient` instance.
-   * @param catalog The HRN that specifies the catalog to which this client
-   * writes.
-   * @param settings Client settings used to control the behavior of the client
-   * instance.
+   *
+   * @param catalog The HRN of the catalog to which this client writes.
+   * @param settings The client settings used to control the behavior
+   * of the client instance.
    */
   IndexLayerClient(client::HRN catalog, client::OlpClientSettings settings);
 
   /**
    * @brief Cancels all the ongoing operations that this client started.
    *
-   * Returns instantly and does not wait for the callbacks.
+   * It returns instantly and does not wait for callbacks.
    * Use this operation to cancel all the pending requests without
    * destroying the actual client instance.
    */
   void CancelPendingRequests();
 
   /**
-   * @brief Publishes an index to an index layer.
-   * @note Content-Type for this request is set implicitly based on the
-   * layer metadata for the target layer on the HERE platform.
-   * @param request PublishIndexRequest object that represents the
-   * parameters for this PublishIndex call.
-   * @return CancellableFuture that contains the PublishIndexResponse.
+   * @brief Publishes the index to the index layer.
+   *
+   * @note The content-type for this request is set implicitly based on
+   * the layer metadata of the target layer.
+   *
+   * @param request The `PublishIndexRequest` object.
+   *
+   * @return `CancellableFuture` that contains `PublishIndexResponse`.
    */
   olp::client::CancellableFuture<PublishIndexResponse> PublishIndex(
       model::PublishIndexRequest request);
 
   /**
-   * @brief Publishes an index to an index layer.
-   * @note Content-Type for this request is set implicitly based on the
-   * layer metadata for the target layer on the HERE platform.
-   * @param request PublishIndexRequest object that represents the
-   * parameters for this PublishIndex call.
-   * @param callback PublishIndexCallback that is called with the
-   * PublishIndexResponse when the operation completes.
-   * @return CancellationToken that can be used to cancel the ongoing
+   * @brief Publishes the index to the index layer.
+   *
+   * @note The content-type for this request is set implicitly based on
+   * the layer metadata of the target layer.
+   *
+   * @param request The `PublishIndexRequest` object.
+   * @param callback `PublishIndexCallback` that is called with
+   * `PublishIndexResponse` when the operation completes.
+   *
+   * @return `CancellationToken` that can be used to cancel the ongoing
    * request.
    */
   olp::client::CancellationToken PublishIndex(
       model::PublishIndexRequest request, PublishIndexCallback callback);
 
   /**
-   * @brief Deletes a data blob that is stored under an index
+   * @brief Deletes the data blob that is stored under the index
    * layer.
-   * @param request DeleteIndexDataRequest object that represents the parameters
-   * for the DeleteIndexData call.
-   * @param callback DeleteIndexDataCallback that is called with
-   * DeleteIndexDataResponse when the operation completes.
-   * @return CancellationToken that can be used to cancel the ongoing
+   *
+   * @param request The `DeleteIndexDataRequest` object.
+   * @param callback `DeleteIndexDataCallback` that is called with
+   * `DeleteIndexDataResponse` when the operation completes.
+   *
+   * @return `CancellationToken` that can be used to cancel the ongoing
    * request.
    */
   olp::client::CancellationToken DeleteIndexData(
       model::DeleteIndexDataRequest request, DeleteIndexDataCallback callback);
 
   /**
-   * @brief Deletes a data blob that is stored under an index
+   * @brief Deletes the data blob that is stored under the index
    * layer.
-   * @param request DeleteIndexDataRequest object that represents the parameters
-   * for DeleteIndexData call.
-   * @return CancellableFuture that contains the DeleteIndexDataResponse.
+   *
+   * @param request The `DeleteIndexDataRequest` object.
+   *
+   * @return `CancellableFuture` that contains `DeleteIndexDataResponse`.
    */
   olp::client::CancellableFuture<DeleteIndexDataResponse> DeleteIndexData(
       model::DeleteIndexDataRequest request);
 
   /**
-   * @brief Updates index information to an index layer.
-   * @param request UpdateIndexRequest object that represents the
-   * parameters for this UpdateIndex call.
-   * @return CancellableFuture that contains the PublishIndexResponse.
+   * @brief Updates index information in the index layer.
+   *
+   * @param request The `UpdateIndexRequest` object.
+   *
+   * @return `CancellableFuture` that contains `PublishIndexResponse`.
    */
   olp::client::CancellableFuture<UpdateIndexResponse> UpdateIndex(
       model::UpdateIndexRequest request);
 
   /**
-   * @brief Updates index information to an index layer
-   * @param request PublishIndexRequest object that represents the
-   * parameters for this PublishIndex call.
-   * @param callback PublishIndexCallback that is called with the
-   * PublishIndexResponse when the operation completes.
-   * @return CancellationToken that can be used to cancel the ongoing
+   * @brief Updates index information in the index layer.
+   *
+   * @param request The `UpdateIndexRequest` object.
+   * @param callback `PublishIndexCallback` that is called with
+   * `PublishIndexResponse` when the operation completes.
+   *
+   * @return `CancellationToken` that can be used to cancel the ongoing
    * request.
    */
   olp::client::CancellationToken UpdateIndex(model::UpdateIndexRequest request,

olp-cpp-sdk-dataservice-write/include/olp/dataservice/write/StreamLayerClient.h

@@ -55,7 +55,7 @@ using PublishSdiiResponse =
     client::ApiResponse<PublishSdiiResult, client::ApiError>;
 using PublishSdiiCallback = std::function<void(PublishSdiiResponse response)>;
 
-/// @brief Client responsible for writing data to a HERE platform stream layer.
+/// Publishes data to a stream layer.
 class DATASERVICE_WRITE_API StreamLayerClient {
  public:
   /// An alias for the flush response.
@@ -65,14 +65,14 @@ class DATASERVICE_WRITE_API StreamLayerClient {
   using FlushCallback = std::function<void(FlushResponse response)>;
 
   /**
-   * @brief StreamLayerClient Constructor.
-   * @param catalog The HRN that specifies the catalog to which this client
-   * writes.
-   * @param client_settings \c StreamLayerClient settings used to control
-   * the behaviour of flush mechanism and other StreamLayerClient specific
+   * @brief Creates the `StreamLayerClient` insatnce.
+   *
+   * @param catalog The HRN of the catalog to which this client writes.
+   * @param client_settings The `StreamLayerClient` settings used to control
+   * the behavior of the flush mechanism and other `StreamLayerClient`
    * properties.
-   * @param settings Client settings used to control behaviour of this
-   * StreamLayerClient instance.
+   * @param settings The client settings used to control the behavior
+   * of the client instance.
    */
   StreamLayerClient(client::HRN catalog,
                     StreamLayerClientSettings client_settings,
@@ -81,93 +81,105 @@ class DATASERVICE_WRITE_API StreamLayerClient {
   /**
    * @brief Cancels all the ongoing publish operations that this client started.
    *
-   * Returns instantly and does not wait for the callbacks.
+   * Returns instantly and does not wait for callbacks.
    * Use this operation to cancel all the pending publish requests without
    * destroying the actual client instance.
-   * @note This operation does not cancel publish requests queued by the \ref
-   * Queue method.
+   *
+   * @note This operation does not cancel publish requests queued by the
+   * `Queue` method.
    */
   void CancelPendingRequests();
 
   /**
-   * @brief Publishes data to a stream layer.
-   * @note Content-Type for this request is implicitly based on the
-   * layer metadata for the target layer on the HERE platform.
-   * @param request PublishDataRequest object that represents the parameters for
-   * this PublishData call.
-   * @return CancellableFuture that contains the PublishDataResponse.
+   * @brief Publishes data to the stream layer.
+   *
+   * @note The content-type for this request is set implicitly based on
+   * the layer metadata of the target layer.
+   *
+   * @param request The `PublishDataRequest` object.
+   *
+   * @return `CancellableFuture` that contains `PublishDataResponse`.
    */
   olp::client::CancellableFuture<PublishDataResponse> PublishData(
       model::PublishDataRequest request);
 
   /**
-   * @brief Publishes data to a stream layer.
-   * @note Content-Type for this request is set implicitly based on the
-   * layer metadata for the target layer on the HERE platform.
-   * @param request PublishDataRequest object that represents the parameters for
-   * this PublishData call.
-   * @param callback PublishDataCallback that is called with the
-   * PublishDataResponse when the operation completes.
-   * @return CancellationToken that can be used to cancel the ongoing
+   * @brief Publishes data to the stream layer.
+   *
+   * @note The content-type for this request is set implicitly based on
+   * the layer metadata of the target layer.
+   *
+   * @param request The `PublishDataRequest` object.
+   * @param callback `PublishDataCallback` that is called with
+   * `PublishDataResponse` when the operation completes.
+   *
+   * @return `CancellationToken` that can be used to cancel the ongoing
    * request.
    */
   olp::client::CancellationToken PublishData(model::PublishDataRequest request,
                                              PublishDataCallback callback);
 
   /**
-   * @brief Enqueues a PublishDataRequest that is sent over the wire.
-   * @param request PublishDataRequest object that represents the parameters for
-   * the call.
-   * @return Optional boost that is boost::none if the queue call is
+   * @brief Enqueues `PublishDataRequest` that is sent over the wire.
+   *
+   * @param request The `PublishDataRequest` object.
+   *
+   * @return An optional boost that is `boost::none` if the queue call is
    * successful. Otherwise, it contains a string with error details.
    */
   boost::optional<std::string> Queue(model::PublishDataRequest request);
 
   /**
-   * @brief Flush PublishDataRequests that were queued via the Queue
-   * API.
-   * @param request \c FlushRequest object thatr represents the parameters for
-   * this \c Flush method call.
-   * @return CancellableFuture that contains the FlushResponse.
+   * @brief Flushes `PublishDataRequests` that are queued via the Queue API.
+   *
+   * @param request The `FlushRequest` object.
+   *
+   * @return `CancellableFuture` that contains `FlushResponse`.
    */
   olp::client::CancellableFuture<FlushResponse> Flush(
       model::FlushRequest request);
 
   /**
-   * @brief Flush PublishDataRequests that were queued via the Queue
-   * API.
-   * @param request \c FlushRequest object that represents the parameters for
-   * this \c Flush method call.
+   * @brief Flushes `PublishDataRequests` that are queued via the Queue API.
+   *
+   * @param request The `FlushRequest` object.
    * @param callback The callback that is called when all the flush
-   * results (see \c FlushResponse) are available.
-   * @return CancellationToken that can be used to cancel the ongoing
+   * results (see `FlushResponse`) are available.
+   *
+   * @return `CancellationToken` that can be used to cancel the ongoing
    * request.
    */
   olp::client::CancellationToken Flush(model::FlushRequest request,
                                        FlushCallback callback);
 
   /**
    * @brief Sends a list of SDII messages to a stream layer.
-   * The SDII message data must be in the SDII MessageList protobuf format. For
-   * more information, please see the HERE platform Sensor Data Ingestion Interface
+   *
+   * SDII message data must be in the SDII Message List protobuf format.
+   * The maximum size is 20 MB.
+   * For more information, see the HERE platform Sensor Data Ingestion Interface
    * documentation and schemas.
-   * @param request PublishSdiiRequest object that represents the parameters for
-   * this PublishSdii call.
-   * @return CancellableFuture that contains the PublishSdiiResponse.
+   *
+   * @param request The `PublishSdiiRequest` object.
+   *
+   * @return `CancellableFuture` that contains `PublishSdiiResponse`.
    */
   olp::client::CancellableFuture<PublishSdiiResponse> PublishSdii(
       model::PublishSdiiRequest request);
 
   /**
    * @brief Sends a list of SDII messages to a stream layer.
-   * The SDII message data must be in the SDII MessageList protobuf format. For
-   * more information, please see the HERE platform Sensor Data Ingestion Interface
+   *
+   * SDII message data must be in the SDII Message List protobuf format.
+   * The maximum size is 20 MB.
+   * For more information, see the HERE platform Sensor Data Ingestion Interface
    * documentation and schemas.
-   * @param request PublishSdiiRequest object that represents the parameters for
-   * this PublishSdii call.
-   * @param callback PublishSdiiCallback that is called with the
-   * PublishSdiiResponse when the operation completes.
-   * @return CancellationToken that can be used to cancel the ongoing
+   *
+   * @param request `PublishSdiiRequest` object.
+   * @param callback `PublishSdiiCallback` that is called with
+   * `PublishSdiiResponse` when the operation completes.
+   *
+   * @return `CancellationToken` that can be used to cancel the ongoing
    * request.
    */
   olp::client::CancellationToken PublishSdii(model::PublishSdiiRequest request,

olp-cpp-sdk-dataservice-write/include/olp/dataservice/write/StreamLayerClientSettings.h

@@ -28,13 +28,12 @@ namespace olp {
 namespace dataservice {
 namespace write {
 
-/**
- * @brief StreamLayerClientSettings settings class for \c StreamLayerClient. Use
- * this class to configure the behaviour of \c StreamLayerClient specific logic.
- */
+/// Configures the behavior of the `StreamLayerClient` specific logic.
 struct DATASERVICE_WRITE_API StreamLayerClientSettings {
   /**
-   * @brief The maximum number of requests that can be stored. Must be positive.
+   * @brief The maximum number of requests that can be stored.
+   *
+   * Make sure it is a positive number.
    */
   size_t maximum_requests = std::numeric_limits<size_t>::max();
 };