Update HERE SDK for C++ documentation (#1345)

nplakhtii · web-flow · commit 7293de68e9b2 · 2022-07-08T17:57:11.000+03:00
Update documentation due to technical writing standards:
Changed Getting Started Guide and README file.

Relates-To: TECHDOCS-1227
Signed-off-by: Nataliia Plakhtii &lt;ext-nataliia.plakhtii@here.com&gt;
diff --git a/README.md b/README.md
@@ -29,21 +29,6 @@ HERE Data SDK for C++ is a C++ client for the <a href="https://platform.here.com
 | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Linux    | <a href="https://codecov.io/gh/heremaps/here-data-sdk-cpp/" target="_blank"><img src="https://codecov.io/gh/heremaps/here-data-sdk-cpp/branch/master/graph/badge.svg" alt="Linux code coverage"/></a> |
 
-## Why use
-
-Data SDK for C++ provides support for the core HERE platform use cases through a set of native C++ interfaces. The Data SDK is intended to save your time and effort on using HERE REST APIs. It provides a set of stable APIs that simplify complex platform operations and keeps up to date with the latest HERE REST API changes.
-
-Data SDK for C++ is a modern (C++11), lightweight, and modular SDK with minimal dependencies targeted towards a wide range of hardware platforms from embedded devices to desktops.
-
-This SDK lets you:
-
-- Authenticate to HERE platform.
-- Read catalog and partition metadata.
-- Retrieve data from versioned, volatile, and stream layers of the platform catalogs.
-- Upload data to the platform.
-
-Additionally, the Data SDK includes classes for work with geospatial tiling schemes that are used by most platform catalog layers.
-
 ## Backward compatibility
 
 We try to develop and maintain our API in a way that preserves its compatibility with the existing applications. Changes in Data SDK for C++ are greatly influenced by the Data API development. Data API introduces breaking changes 6 months in advance. Therefore, you may need to migrate to a new version of Data SDK for C++ every half a year.
@@ -93,100 +78,6 @@ sudo apt-get update && sudo apt-get --yes install git g++ make cmake libssl-dev
 > #### Note
 > Please note that on some Linux distribution, the default libcurl version can be lower than the required v7.52.0. In that case, you need to install the required libcurl version from a different PPA.
 
-## Install the SDK
-
-By default, the Data SDK downloads and compiles its dependencies. The versions of the downloaded dependencies may conflict with the versions that are already installed on your system. Therefore, the downloaded dependencies are not added to the install targets.
-
-You can use the Data SDK in your CMake project or install it on your system.
-
-Тo use the Data SDK directly in your CMake project, add the Data SDK via `add_subdirectory()`.
-
-**To install the Data SDK on your system:**
-
-1. Install all the dependencies needed for the Data SDK.<br>For more information on dependencies, see the [Dependencies](#dependencies) and [Additional Linux dependencies](#additional-linux-dependencies) sections.
-
-2. (Optional) To find the required dependencies in the system, set the `OLP_SDK_BUILD_EXTERNAL_DEPS` flag to `OFF`.
-
-3. (Optional) To build the Data SDK as a shared library, set the `BUILD_SHARED_LIBS` flag to `ON`.
-
-**Example**
-
-The following command builds and installs the Data SDK:
-
-```bash
-cmake --build . --target install
-```
-
-## Build the SDK
-
-<a href="https://cmake.org/download/" target="_blank">CMake</a> is the main build system. The minimal required version of CMake is 3.9.
-
-CMake downloads <a href="https://github.com/google/leveldb" target="_blank">LevelDB</a>, <a href="https://github.com/google/snappy" target="_blank">Snappy</a>, <a href="https://github.com/Tencent/rapidjson" target="_blank">RapidJSON</a>, and <a href="https://www.boost.org/" target="_blank">Boost</a>. To disable downloading, set `OLP_SDK_BUILD_EXTERNAL_DEPS` to `OFF`. For details on CMake flags, see the [related](#cmake-flags) section.
-
-**To build the Data SDK:**
-
-1. Clone the repository folder.
-2. In the root of the repository folder, run the following commands:
-
-```bash
-    mkdir build && cd build
-    cmake ..
-    cmake --build .
-```
-
-If you cannot build the Data SDK on Windows using this instruction, see [Build on Windows](#build-on-windows).
-
-<h6 id="build-on-windows"></h6>
-
-### Build on Windows
-
-<a href="https://dev.azure.com/heremaps/here-data-sdk/_build/latest?definitionId=3&branchName=master" target="_blank"><img src="https://dev.azure.com/heremaps/here-data-sdk/_apis/build/status/heremaps.here-data-sdk-cpp?branchName=master&jobName=Windows_build" alt="Windows build status"/></a>
-
-We assume that you have installed CMake, Microsoft Visual Studio 2017, and the Visual C++ tools for CMake component.
-
-**To build the Data SDK on Windows:**
-
-1. Launch Microsoft Visual Studio as administrator.
-
-2. Open the folder containing the Data SDK or a CMake-based project that uses the Data SDK.
-
-3. In Microsoft Visual Studio, check that the target does not contain "(Default)".<br>For example, select "x64-Debug" instead of "x64-Debug (Default)".
-
-4. Using the CMake menu provided by the Visual C++ tools for CMake, generate the `.cmake` files, and build the entire project with default options.
-
-> #### Note
-> Microsoft Visual Studio uses a default build directory that has a long path name. Since dependencies for the Data SDK are installed within the build directory, it is recommended that you edit the generated `CMakeSettings.json` file and change the build directory path name to a shorter path name. This ensures that the maximum length of each path is not greater than 260 characters. For details, see the <a href="https://docs.microsoft.com/en-us/windows/desktop/fileio/naming-a-file" target="_blank">Naming Files, Paths, and Namespaces</a> section of the Windows Dev Center documentation.
-
-### Generate documentation with Doxygen
-
-If you want to build documentation from annotated source code, you need to have <a href="http://www.doxygen.nl/" target="_blank">Doxygen</a> and CMake version 3.9 or later.
-
-To generate Doxygen documentation, set the `OLP_SDK_BUILD_DOC` flag to `ON` when running the CMake configuration:
-
-```bash
-mkdir build && cd build
-cmake -DOLP_SDK_BUILD_DOC=ON ..
-cmake --build . --target docs
-```
-
-<h6 id="cmake-flags"></h6>
-
-### CMake flags
-
-| Flag | Description |
-| :- | :- |
-| `BUILD_SHARED_LIBS` | Defaults to `OFF`. If enabled, all libraries are built as shared. |
-| `OLP_SDK_BUILD_DOC` | Defaults to `OFF`. If enabled, the API reference is generated in your build directory.<br> **Note:** Before you download the API reference, install <a href="http://www.doxygen.nl/" target="_blank">Doxygen</a>. |
-| `OLP_SDK_ENABLE_TESTING` | Defaults to `ON`. If enabled, unit tests are built for each library. |
-| `OLP_SDK_BUILD_EXTERNAL_DEPS` | Defaults to `ON`. If enabled, CMake downloads and compiles dependencies. |
-| `OLP_SDK_NO_EXCEPTION` | Defaults to `OFF`. If enabled, all libraries are built without exceptions. |
-| `OLP_SDK_BOOST_THROW_EXCEPTION_EXTERNAL` | Defaults to `OFF`. When `OLP_SDK_NO_EXCEPTION` is `ON`, `boost` requires `boost::throw_exception()` to be defined. If enabled, the external definition of `boost::throw_exception()` is used. Otherwise, the library uses own definition. |
-| `OLP_SDK_MSVC_PARALLEL_BUILD_ENABLE` (Windows Only) | Defaults to `ON`. If enabled, the `/MP` compilation flag is added to build the Data SDK using multiple cores. |
-| `OLP_SDK_DISABLE_DEBUG_LOGGING`| Defaults to `OFF`. If enabled, the debug and trace level log messages are not printed. |
-| `OLP_SDK_ENABLE_DEFAULT_CACHE `| Defaults to `ON`. If enabled, the default cache implementation based on the LevelDB backend is enabled. |
-| `OLP_SDK_ENABLE_DEFAULT_CACHE_LMDB `| Defaults to `OFF`. If enabled, the default cache implementation based on the LMDB backend is enabled. |
-| `OLP_SDK_ENABLE_ANDROID_CURL`| Defaults to `OFF`. If enabled, libcurl will be used instead of the Android native HTTP client. |
-
 ## Use the SDK
 
 To learn how to use the Data SDK, see the <a href="https://github.com/heremaps/here-data-sdk-cpp/blob/master/docs/GettingStartedGuide.md" target="_blank">Getting Started Guide</a>, <a href="https://developer.here.com/documentation/sdk-cpp/dev_guide/index.html" target="blank">Developer Guide</a>, and <a href="https://developer.here.com/documentation/sdk-cpp/api_reference/index.html" target="_blank">API Reference</a>.
diff --git a/docs/GettingStartedGuide.md b/docs/GettingStartedGuide.md
@@ -9,14 +9,16 @@ Working with the Data SDK requires knowledge of the following subjects:
 - Basic understanding of the core [HERE platform concepts](#concepts).
 - Basic proficiency with C++11 and CMake.
 
+For the terms and conditions covering this documentation, see the [HERE Documentation License](https://legal.here.com/en-gb/terms/documentation-license).
+
 ## Concepts
 
 To use HERE Data SDK for C++, you need to understand the following concepts related to the HERE platform:
 
-- [Catalogs](https://developer.here.com/documentation/data-user-guide/portal/layers/catalogs.html)
-- [Layers](https://developer.here.com/documentation/data-user-guide/portal/layers/layers.html)
-- [Partitions](https://developer.here.com/documentation/data-user-guide/portal/layers/partitions.html)
-- [HERE Resource Names (HRNs)](https://developer.here.com/documentation/data-user-guide/shared_content/topics/concepts/hrn.html)
+- [Catalogs](https://developer.here.com/documentation/data-api/data_dev_guide/rest/catalogs.html)
+- [Layers](https://developer.here.com/documentation/data-api/data_dev_guide/rest/layers.html)
+- [Partitions](https://developer.here.com/documentation/data-api/data_dev_guide/rest/partitions.html)
+- [HERE Resource Names (HRNs)](https://developer.here.com/documentation/data-api/data_dev_guide/rest/hrn.html)
 
 For more details, see the [Data User Guide](https://developer.here.com/documentation/data-user-guide/index.html).
 
@@ -26,6 +28,70 @@ To work with catalog or service requests to the HERE platform, you need to get a
 
 You can authenticate to the HERE platform within your application with the platform credentials available on the HERE Portal by means of Data SDK for C++ authentication library. For the available authentication options, see the [Identity & Access Management Developer Guide](https://developer.here.com/documentation/identity-access-management/dev_guide/index.html).
 
+## Install the SDK
+
+By default, the Data SDK downloads and compiles its dependencies. The versions of the downloaded dependencies may conflict with the versions that are already installed on your system. Therefore, the downloaded dependencies are not added to the install targets.
+
+You can use the Data SDK in your CMake project or install it on your system.
+
+Тo use the Data SDK directly in your CMake project, add the Data SDK via `add_subdirectory()`.
+
+**To install the Data SDK on your system:**
+
+1. Install all the dependencies needed for the Data SDK.<br>For more information on dependencies, see the [Dependencies](#dependencies) and [Additional Linux dependencies](#additional-linux-dependencies) sections.
+
+2. (Optional) To find the required dependencies in the system, set the `OLP_SDK_BUILD_EXTERNAL_DEPS` flag to `OFF`.
+
+3. (Optional) To build the Data SDK as a shared library, set the `BUILD_SHARED_LIBS` flag to `ON`.
+
+**Example**
+
+The following command builds and installs the Data SDK:
+
+```bash
+cmake --build . --target install
+```
+
+## Build the SDK
+
+<a href="https://cmake.org/download/" target="_blank">CMake</a> is the main build system. The minimal required version of CMake is 3.9.
+
+CMake downloads <a href="https://github.com/google/leveldb" target="_blank">LevelDB</a>, <a href="https://github.com/google/snappy" target="_blank">Snappy</a>, <a href="https://github.com/Tencent/rapidjson" target="_blank">RapidJSON</a>, and <a href="https://www.boost.org/" target="_blank">Boost</a>. To disable downloading, set `OLP_SDK_BUILD_EXTERNAL_DEPS` to `OFF`. For details on CMake flags, see the [related](#cmake-flags) section.
+
+**To build the Data SDK:**
+
+1. Clone the repository folder.
+2. In the root of the repository folder, run the following commands:
+
+```bash
+    mkdir build && cd build
+    cmake ..
+    cmake --build .
+```
+
+If you cannot build the Data SDK on Windows using this instruction, see [Build on Windows](#build-on-windows).
+
+<h6 id="build-on-windows"></h6>
+
+### Build on Windows
+
+<a href="https://dev.azure.com/heremaps/here-data-sdk/_build/latest?definitionId=3&branchName=master" target="_blank"><img src="https://dev.azure.com/heremaps/here-data-sdk/_apis/build/status/heremaps.here-data-sdk-cpp?branchName=master&jobName=Windows_build" alt="Windows build status"/></a>
+
+We assume that you have installed CMake, Microsoft Visual Studio 2017, and the Visual C++ tools for CMake component.
+
+**To build the Data SDK on Windows:**
+
+1. Launch Microsoft Visual Studio as administrator.
+
+2. Open the folder containing the Data SDK or a CMake-based project that uses the Data SDK.
+
+3. In Microsoft Visual Studio, check that the target does not contain "(Default)".<br>For example, select "x64-Debug" instead of "x64-Debug (Default)".
+
+4. Using the CMake menu provided by the Visual C++ tools for CMake, generate the `.cmake` files, and build the entire project with default options.
+
+> #### Note
+> Microsoft Visual Studio uses a default build directory that has a long path name. Since dependencies for the Data SDK are installed within the build directory, it is recommended that you edit the generated `CMakeSettings.json` file and change the build directory path name to a shorter path name. This ensures that the maximum length of each path is not greater than 260 characters. For details, see the <a href="https://docs.microsoft.com/en-us/windows/desktop/fileio/naming-a-file" target="_blank">Naming Files, Paths, and Namespaces</a> section of the Windows Dev Center documentation.
+
 ## Available components
 
 Data SDK for C++ contains separate libraries, each of which has a distinct functionality. For more information about the components, see the [architectural overview](OverallArchitecture.md).
@@ -52,6 +118,36 @@ target_link_libraries(example_app
 )
 ```
 
+### Generate documentation with Doxygen
+
+If you want to build documentation from annotated source code, you need to have <a href="http://www.doxygen.nl/" target="_blank">Doxygen</a> and CMake version 3.9 or later.
+
+To generate Doxygen documentation, set the `OLP_SDK_BUILD_DOC` flag to `ON` when running the CMake configuration:
+
+```bash
+mkdir build && cd build
+cmake -DOLP_SDK_BUILD_DOC=ON ..
+cmake --build . --target docs
+```
+
+<h6 id="cmake-flags"></h6>
+
+### CMake flags
+
+| Flag | Description |
+| :- | :- |
+| `BUILD_SHARED_LIBS` | Defaults to `OFF`. If enabled, all libraries are built as shared. |
+| `OLP_SDK_BUILD_DOC` | Defaults to `OFF`. If enabled, the API reference is generated in your build directory.<br> **Note:** Before you download the API reference, install <a href="http://www.doxygen.nl/" target="_blank">Doxygen</a>. |
+| `OLP_SDK_ENABLE_TESTING` | Defaults to `ON`. If enabled, unit tests are built for each library. |
+| `OLP_SDK_BUILD_EXTERNAL_DEPS` | Defaults to `ON`. If enabled, CMake downloads and compiles dependencies. |
+| `OLP_SDK_NO_EXCEPTION` | Defaults to `OFF`. If enabled, all libraries are built without exceptions. |
+| `OLP_SDK_BOOST_THROW_EXCEPTION_EXTERNAL` | Defaults to `OFF`. When `OLP_SDK_NO_EXCEPTION` is `ON`, `boost` requires `boost::throw_exception()` to be defined. If enabled, the external definition of `boost::throw_exception()` is used. Otherwise, the library uses own definition. |
+| `OLP_SDK_MSVC_PARALLEL_BUILD_ENABLE` (Windows Only) | Defaults to `ON`. If enabled, the `/MP` compilation flag is added to build the Data SDK using multiple cores. |
+| `OLP_SDK_DISABLE_DEBUG_LOGGING`| Defaults to `OFF`. If enabled, the debug and trace level log messages are not printed. |
+| `OLP_SDK_ENABLE_DEFAULT_CACHE `| Defaults to `ON`. If enabled, the default cache implementation based on the LevelDB backend is enabled. |
+| `OLP_SDK_ENABLE_DEFAULT_CACHE_LMDB `| Defaults to `OFF`. If enabled, the default cache implementation based on the LMDB backend is enabled. |
+| `OLP_SDK_ENABLE_ANDROID_CURL`| Defaults to `OFF`. If enabled, libcurl will be used instead of the Android native HTTP client. |
+
 ## Reference documentation
 
 The API reference documentation for Data SDK for C++ is available on our [GitHub Pages](https://heremaps.github.io/here-data-sdk-cpp/).
@@ -64,4 +160,3 @@ HERE Data SDK for C++ contains several example programs that demonstrate some of
 - [Read example for a stream layer](dataservice-read-from-stream-layer-example.md) – demonstrates how to get data from a stream layer.
 - [Cache example](dataservice-cache-example.md) – demonstrates how to get partition data and work with a mutable and protected cache.
 - [Write example](dataservice-write-example.md) – demonstrates how to publish data to OLP.
-
