Review/add the API doc (geo folder - part 2) (#1195)

In olp-cpp-sdk-core/include/olp/core/geo/coordinates&projection,
review and modify the existing documentation and add missing
descriptions so that we have fewer errors when building the API ref.

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

Author: HalynaDumych

olp-cpp-sdk-core/include/olp/core/geo/tiling/HalfQuadTreeSubdivisionScheme.h

@@ -27,10 +27,10 @@ namespace olp {
 namespace geo {
 
 /**
- * @brief Half-quadtree subdivision scheme.
+ * @brief A subdivision scheme used to represent half quadtrees.
  *
- * Subdivides 0-th level tile into left and right parts; on other levels same as
- * quadtree.
+ * Subdivides tiles of level 0 into left and right parts.
+ * At other levels, it subdivides tiles into four equal-sized child tiles.
  */
 class CORE_API HalfQuadTreeSubdivisionScheme final : public ISubdivisionScheme {
  public:

olp-cpp-sdk-core/include/olp/core/geo/tiling/ISubdivisionScheme.h

@@ -28,43 +28,44 @@ namespace olp {
 namespace geo {
 
 /**
- * Abstract tiling subdivision scheme.
+ * @brief An abstract tiling subdivision scheme.
  */
 class CORE_API ISubdivisionScheme {
  public:
   virtual ~ISubdivisionScheme() = default;
 
   /**
-   * Check whether two schemes are equal.
+   * @brief Checks whether two schemes are equal.
    *
-   * @param[in] other Other scheme.
+   * @param[in] other The other scheme.
    *
-   * @return True if equal, false otherwise.
+   * @return True if the schemes are equal; false otherwise.
    */
   virtual bool IsEqualTo(const ISubdivisionScheme& other) const = 0;
 
   /**
-   * Get unique scheme name.
+   * @brief Gets the unique scheme name.
    *
-   * @return Scheme name.
+   * @return The scheme name.
    */
   virtual const std::string& GetName() const = 0;
 
   /**
-   * Get number of subtiles a tile splits into at given level.
+   * @brief Gets the number of child tiles into which a tile splits
+   * at a given level.
    *
-   * @param[in] level Subdivision level.
+   * @param[in] level The subdivision level.
    *
-   * @return Horizontal and vertical number of subtiles (e.g. 2x2).
+   * @return The horizontal and vertical numbers of child tiles (for example, 2 × 2).
    */
   virtual math::Size2u GetSubdivisionAt(unsigned level) const = 0;
 
   /**
-   * Get size of a given level.
+   * @brief Gets the size of a given level.
    *
-   * @param[in] level Subdivision level.
+   * @param[in] level The subdivision level.
    *
-   * @return Horizontal and vertical number of tiles (e.g. 2^level x 2^level).
+   * @return The horizontal and vertical numbers of tiles (for example, 2^level × 2^level).
    */
   virtual math::Size2u GetLevelSize(unsigned level) const = 0;
 };

olp-cpp-sdk-core/include/olp/core/geo/tiling/ITilingScheme.h

@@ -24,10 +24,24 @@
 namespace olp {
 namespace geo {
 
+/**
+ * @brief Represents how data is tiled.
+ */
 class CORE_API ITilingScheme {
  public:
   virtual ~ITilingScheme() = default;
+  /**
+   * @brief Gets the subdivision scheme.
+   *
+   * @return The subdivision scheme.
+   */
   virtual const ISubdivisionScheme& GetSubdivisionScheme() const = 0;
+
+  /**
+   * @brief Gets the identity projection.
+   *
+   * @return The identity projection.
+   */
   virtual const IProjection& GetProjection() const = 0;
 };
 

olp-cpp-sdk-core/include/olp/core/geo/tiling/QuadTreeSubdivisionScheme.h

@@ -27,9 +27,9 @@ namespace olp {
 namespace geo {
 
 /**
- * @brief Quadtree subdivision scheme.
+ * @brief A quadtree subdivision scheme.
  *
- * Subdivides tiles on all levels into four equal-sized subtiles.
+ * Subdivides tiles at all levels into four equal-sized sub-tiles.
  */
 class CORE_API QuadTreeSubdivisionScheme final : public ISubdivisionScheme {
  public:

olp-cpp-sdk-core/include/olp/core/geo/tiling/SubTiles.h

@@ -29,22 +29,58 @@
 namespace olp {
 namespace geo {
 
+/**
+ * @brief A container of child tiles.
+ */
 class CORE_API SubTiles {
   friend class Iterator;
 
  public:
+  /// The tile key iterator.
   class Iterator : public std::iterator<std::forward_iterator_tag, TileKey> {
     friend class SubTiles;
 
    public:
+    /// An alias for the tile key.
     using ValueType = TileKey;
 
+    /**
+     * @brief Gets a reference to the tile key.
+     *
+     * @return The reference to the tile key.
+     */
     ValueType operator*() const;
 
+    /**
+     * @brief Iterates to the next tile.
+     *
+     * @return A reference to this.
+     */
     Iterator& operator++();
+
+    /**
+     * @brief Iterates the specified number of times to the next tile.
+     *
+     * @return A new iterator.
+     */
     Iterator operator++(int);
 
+    /**
+     * @brief Checks whether the iterators are equal.
+     *
+     * @param other The other iterator.
+     *
+     * @return True if the iterators are equal; false otherwise.
+     */
     bool operator==(Iterator& other) const;
+
+    /**
+     * @brief Checks whether the iterators are not equal.
+     *
+     * @param other The other iterator.
+     *
+     * @return True if the iterators are not equal; false otherwise.
+     */
     bool operator!=(Iterator& other) const;
 
    private:
@@ -54,20 +90,39 @@ class CORE_API SubTiles {
     std::uint32_t index_{0};
   };
 
+  /// An alias for the iterator.
   using ConstIterator = Iterator;
 
+  /**
+   * @brief Creates a `SubTiles` instance.
+   *
+   * @param tile_key The tile key.
+   * @param level The tile level.
+   * @param mask The mask that indicates how many tiles should be included.
+   */
   SubTiles(const TileKey& tile_key, std::uint32_t level = 1,
            std::uint16_t mask = ~0);
 
+  /**
+   * @brief Gets the size of the child tile.
+   *
+   * @return The size of the child tile.
+   */
   size_t Size() const;
 
+  /// Returns an iterator to the beginning.
   Iterator begin();
+  /// Returns an iterator to the end.
   Iterator end();
 
+  /// Returns a constant iterator to the beginning.
   ConstIterator begin() const;
+  /// Returns a constant iterator to the end.
   ConstIterator end() const;
 
+  /// Returns a constant iterator to the beginning of the container.
   ConstIterator cbegin() const;
+  /// Returns a constant iterator to the end of the container.
   ConstIterator cend() const;
 
  private: