Improve Doxygen for VersionedLayerClient

- add additional info about versions
- add usage example
- add info about saving request when version is provided

Resolves: OLPEDGE-854
Signed-off-by: Diachenko Mykahilo <[email protected]>

Author: diachenko-mischa

olp-cpp-sdk-dataservice-read/include/olp/dataservice/read/VersionedLayerClient.h

@@ -40,87 +40,136 @@ namespace read {
 class VersionedLayerClientImpl;
 
 /**
- * @brief The VersionedLayerClient aimed to acquire data from OLP services.
+ * @brief Client that acquires data from an OLP versioned layer. The versioned
+ * layer stores slowly-changing data that must remain logically consistent with
+ * other layers in a catalog.
+ *
+ * @note When you request a particular version of data from a versioned layer,
+ * the partition that gets returned may have a lower version number than you
+ * requested. Only those layers and partitions that are updated have their
+ * version updated to the catalog new version number. The version of a
+ * layer or partition represents the catalog version in which the layer or
+ * partition was last updated.
+ *
+ * @note If a catalog version is not specified, the latest version is used. To
+ * query the latest version of a catalog, an additional request to OLP is
+ * needed.
+ *
+ * Example with version provided that saves one network request:
+ * @code{.cpp}
+ * auto task_scheduler =
+ *    olp::client::OlpClientSettingsFactory::CreateDefaultTaskScheduler(1u);
+ * auto http_client = olp::client::
+ *    OlpClientSettingsFactory::CreateDefaultNetworkRequestHandler();
+ *
+ * olp::authentication::Settings settings{"Your.Key.Id", "Your.Key.Secret"};
+ * settings.task_scheduler = task_scheduler;
+ * settings.network_request_handler = http_client;
+ *
+ * olp::client::AuthenticationSettings auth_settings;
+ * auth_settings.provider =
+ *     olp::authentication::TokenProviderDefault(std::move(settings));
+ *
+ * auto client_settings = olp::client::OlpClientSettings();
+ * client_settings.authentication_settings = auth_settings;
+ * client_settings.task_scheduler = std::move(task_scheduler);
+ * client_settings.network_request_handler = std::move(http_client);
+ *
+ * VersionedLayerClient client{"hrn:here:data:::your-catalog-hrn" "your-layer-id", client_settings};
+ * auto callback = [](olp::client::ApiResponse<olp::model::Data, olp::client::ApiError> response) {};
+ * auto request = DataRequest().WithVersion(100).WithPartitionId("269");
+ * auto token = client.GetData(request, callback);
+ * @endcode
+ *
+ * @see
+ * https://developer.here.com/olp/documentation/data-api/data_dev_guide/shared_content/topics/olp/concepts/layers.html
+ * @see
+ * https://developer.here.com/olp/documentation/data-api/data_dev_guide/rest/getting-data-versioned.html
  */
 class DATASERVICE_READ_API VersionedLayerClient final {
  public:
   /**
    * @brief VersionedLayerClient constructor
-   * @param catalog a catalog that the versioned layer client uses during
-   * requests.
-   * @param layer_id a layer id that the versioned layer client uses during
+   * @param catalog HRN of the catalog to which this layer belongs.
+   * @param layer_id Layer ID of the versioned layer that is used for all
    * requests.
-   * @param settings settings used to control the client instance behavior.
+   * @param settings Settings used to control the client instance behavior.
    */
   VersionedLayerClient(client::HRN catalog, std::string layer_id,
                        client::OlpClientSettings settings);
 
   ~VersionedLayerClient();
 
   /**
-   * @brief Fetches data for a partition or data handle asynchronously. If the
-   * specified partition or data handle cannot be found in the layer, the
-   * callback will be invoked with an empty DataResponse (nullptr for result and
-   * error). If neither Partition Id or Data Handle were set in the request, the
-   * callback will be invoked with an error with ErrorCode::InvalidRequest.
-   * @param data_request contains the complete set of request parameters.
-   * \note \c DataRequest's GetLayerId value will be ignored and the parameter
-   * from the constructor will be used instead.
-   * @param callback will be invoked once the DataResult is available, or an
-   * error is encountered.
-   * @return A token that can be used to cancel this request.
+   * @brief Fetches data for a partition ID or data handle asynchronously.
+   *
+   * If the specified partition ID or data handle cannot be found in the layer,
+   * the callback is invoked with an empty DataResponse (a nullptr result and
+   * error). If the partition ID or data handle are not set in the request, the
+   * callback is invoked with the error ErrorCode::InvalidRequest. If the
+   * version is not specified, an additional request to OLP is created to
+   * retrieve the latest available partition version.
+   *
+   * @param data_request Contains the complete set of the request parameters.
+   * @note GetLayerId value of the \c DataRequest is ignored, and the parameter
+   * from the constructor is used instead.
+   * @param callback Is invoked once the DataResult is available or an error is
+   * encountered.
+   * @return Token that can be used to cancel the GetData request.
    */
   client::CancellationToken GetData(DataRequest data_request,
                                     DataResponseCallback callback);
 
   /**
-   * @brief fetches a list partitions for given generic layer asynchronously.
-   * @param request contains the complete set of request parameters.
-   * \note \c PartitionsRequest's GetLayerId value will be ignored and the
-   * parameter from the constructor will be used instead.
-   * @param callback will be invoked once the list of partitions is available,
-   * or an error is encountered.
-   * @return A token that can be used to cancel this request
+   * @brief Fetches a list of partitions for the given generic layer
+   * asynchronously.
+   * @param partitions_request Contains the complete set of the request
+   * parameters.
+   * @note GetLayerId value of the \c PartitionsRequest is ignored, and the
+   * parameter from the constructor is used instead.
+   * @param callback Is invoked once the list of partitions is available or an
+   * error is encountered.
+   * @return Token that can be used to cancel the GetPartitions request.
    */
   client::CancellationToken GetPartitions(PartitionsRequest partitions_request,
                                           PartitionsResponseCallback callback);
 
   /**
    * @brief Pre-fetches a set of tiles asychronously.
    *
-   * This method recursively downloads all tilekeys from minLevel to maxLevel
-   * specified in the \c PrefetchTilesRequest's properties. This will help to
-   * reduce the network load by using the pre-fetched tiles' data from cache.
+   * This method recursively downloads all tilekeys from the minLevel to
+   * maxLevel parameters of the \c PrefetchTilesRequest. It helps to reduce the
+   * network load by using the pre-fetched tiles data from cache.
    *
-   * \note - this does not guarantee that all tiles are available offline, as
-   * the cache might overflow and data might be evicted at any point.
+   * @note This does not guarantee that all tiles are available offline as the
+   * cache might overflow and data might be evicted at any point.
    *
-   * @param request contains the complete set of request parameters.
-   * \note The \c PrefetchTilesRequest's GetLayerId value will be ignored and
-   * the parameter from constructore will be used instead.
-   * @param callback will be invoked once the \c PrefetchTilesResult is
-   * available, or an error is encountered.
-   * @return A token that can be used to cancel this request.
+   * @param request Contains the complete set of the request parameters.
+   * @note GetLayerId value of the \c PrefetchTilesRequest is ignored, and the
+   * parameter from the constructor is used instead.
+   * @param callback Is invoked once the \c PrefetchTilesResult is available or
+   * an error is encountered.
+   * @return Token that can be used to cancel this request.
    */
   client::CancellationToken PrefetchTiles(
       PrefetchTilesRequest request, PrefetchTilesResponseCallback callback);
 
   /**
    * @brief Pre-fetches a set of tiles asychronously.
    *
-   * This method recursively downloads all tilekeys from minLevel to maxLevel
-   * specified in the \c PrefetchTilesRequest's properties. This will help to
-   * reduce the network load by using the pre-fetched tiles' data from cache.
+   * This method recursively downloads all tilekeys from the minLevel to
+   * maxLevel specified in the \c PrefetchTilesRequest properties. This helps to
+   * reduce the network load by using the pre-fetched tiles data from cache.
    *
-   * \note - this does not guarantee that all tiles are available offline, as
-   * the cache might overflow and data might be evicted at any point.
+   * @note This does not guarantee that all tiles are available offline as the
+   * cache might overflow and data might be evicted at any point.
    *
-   * @param request contains the complete set of request parameters.
-   * \note The \c PrefetchTilesRequest's GetLayerId value will be ignored and
-   * the parameter from constructore will be used instead.
-   * @return CancellableFuture of type \c PrefetchTilesResponse, which when
-   * complete will contain the data or an error. Alternatively, the
-   * \c CancellableFuture can be used to cancel this request.
+   * @param request Contains the complete set of the request parameters.
+   * @note GetLayerId value of the \c PrefetchTilesRequest is ignored, and
+   * the parameter from the constructor is used instead.
+   * @return CancellableFuture of the \c PrefetchTilesResponse type. When
+   * completed, the CancellableFuture contains data or an error. Alternatively,
+   * the \c CancellableFuture can be used to cancel this request.
    */
   client::CancellableFuture<PrefetchTilesResponse> PrefetchTiles(
       PrefetchTilesRequest request);