Doc: Update OSM example docs

Minor updates to the OSM example documentation

Pick-to: 6.7
Change-Id: I3a903246e9660abde552ac51628372265a4cc10e
Reviewed-by: Sadegh Taghavi <sadegh.taghavi@qt.io>
Reviewed-by: Mats Honkamaa <mats.honkamaa@qt.io>
Reviewed-by: Esa Törmänen <esa.tormanen@qt.io>

1 files changed, 56 insertions, 25 deletions

diff --git a/examples/demos/osmbuildings/doc/src/osmbuildings.qdoc b/examples/demos/osmbuildings/doc/src/osmbuildings.qdoc
index fef0c223d..75e1a6edc 100644
--- a/examples/demos/osmbuildings/doc/src/osmbuildings.qdoc
+++ b/examples/demos/osmbuildings/doc/src/osmbuildings.qdoc
@@ -1,4 +1,4 @@
-// Copyright (C) 2017 The Qt Company Ltd.
+// Copyright (C) 2024 The Qt Company Ltd.
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 /*!
@@ -6,22 +6,28 @@
     \examplecategory {3D}
     \ingroup qtquickdemos
     \example demos/osmbuildings
-    \brief A 3d building viewer of OSM buildings map data.
+    \brief A 3D building viewer of OSM (OpenStreetMap) buildings map data.
     \meta {tag} {demo,quick,3d}
     \borderedimage osmbuildings.jpg
 
-    The \e{OSMBuildings} application demonstrates of using 3d building data from OSM servers
-    or from locally limited data set when the server isn't available,
-    to create 3d building geometry from the data to show on the map.
+    \section1 Overview
+
+    This application demonstrates how to create 3D building geometry for display on a map using data
+    from OpenStreetMap (OSM) servers or a locally limited data set when the server is unavailable.
+
+    \section2 Queue handling
 
     The application uses a queue to handle concurrent requests to boost up the loading process of
-    the maps and the building data.
+    maps and building data.
 
     \quotefromfile demos/osmbuildings/request.cpp
     \skipto OSMRequest::OSMRequest
     \printuntil m_queuesTimer.setInterval(0);
 
-    It implements a custom request handler class for fetching the data from the OSM building and map servers.
+   \section2 Fetching and parsing data
+
+    A custom request handler class is implemented for fetching the data from the OSM building
+    and map servers.
 
     \quotefromfile demos/osmbuildings/request.cpp
     \skipto OSMRequest::getBuildingsData
@@ -29,53 +35,81 @@
     \skipto OSMRequest::getMapsData
     \printuntil } );
 
-    Also it's parsing the online data to convert it to a QVarianList of keys and values of Geo formats e.g. QGeoPolygon.
+    The application parses the online data to convert it to a \l{QVariant} list of keys and values
+    in geo formats such as \l{QGeoPolygon}.
 
     \quotefromfile demos/osmbuildings/request.cpp
     \skipto importGeoJson(QJsonDocument::fromJson
     \printuntil --m_buildingsNumberOfRequestsInFlight;
 
-    The building parsed data send to a custom geometry item to convert the geo coordinate to proper 3d coordinates.
+    The parsed building data is sent to a custom geometry item to convert the geo coordinates to 3D
+    coordinates.
 
     \quotefromfile demos/osmbuildings/geometry.cpp
     \skipto convertGeoCoordToVertexPosition
     \printuntil }
 
-    It generates necessary data for the index buffer and vertex buffer e.g. Position, Normal, Tangent, UV, ...
+    The required data for the index and vertex buffers, such as position, normals, tangents,
+    and UV coordinates, is generated.
 
     \quotefromfile demos/osmbuildings/geometry.cpp
     \skipto for ( const QVariant &baseData : geoVariantsList )
+	\printuntil for ( const QGeoCoordinate &buildingPoint : buildingCoords )
+	\dots 3
+	\skipto std::vector<PolygonVertices> roofPolygonsVerices
     \printuntil clear()
 
-    The map downloaded PNG data send to a custom QQuick3DTextureData item to convert the PNG format data to a texture
-    for use as a texture for map tiles.
+    The downloaded PNG data is sent to a custom QQuick3DTextureData item to convert the PNG format
+    to a texture for map tiles.
 
     \quotefromfile demos/osmbuildings/manager.cpp
     \skipto CustomTextureData::setImageData
     \printuntil }
 
-    It uses camera position, orientation, zoom level, and tilt to find the nearest tiles in the view.
+    The application uses camera position, orientation, zoom level, and tilt to find the nearest
+    tiles in the view.
 
     \quotefromfile demos/osmbuildings/manager.cpp
     \skipto OSMManager::setCameraProperties
     \printuntil ->getMapsData( queue );
 
-    Also generates the tiles request queue to submit as a request.
+    Generates the tiles request queue.
 
     \quotefromfile demos/osmbuildings/manager.cpp
     \skipto OSMManager::addBuildingRequestToQueue
     \printuntil }
 
-    The app uses a custom camera controller to navigate through the map,
-    using the left mouse button to pan the map and right mouse button to rotate,
-    and mouse wheel to zoom the camera.
+    \section2 Controls
+
+    When you run the application, use the following controls for navigation.
+
+    \table
+      \header
+         \li
+         \li Windows
+         \li Android
+      \row
+        \li Pan
+        \li Left mouse button + drag
+        \li Drag
+      \row
+        \li Zoom
+        \li Mouse wheel
+        \li Pinch
+      \row
+        \li Rotate
+        \li Right mouse button + drag
+        \li n/a
+    \endtable
 
     \quotefromfile demos/osmbuildings/Main.qml
     \skipto OSMCameraController
     \printuntil }
 
-    Every chunk of the map tile consists of two types of the QML model and custom material.
-    one using a rectangle as a base to render tile map texture.
+    \section2 Rendering
+
+    Every chunk of the map tile consists of a QML model (the 3D geometry) and a custom material
+    which uses a rectangle as a base to render the tilemap texture.
 
     \quotefromfile demos/osmbuildings/Main.qml
     \skipto id: chunkModelMap
@@ -85,7 +119,7 @@
     \printuntil ]
     \printuntil }
 
-    It's using a custom geometry to render tile buildings.
+    The application uses custom geometry to render tile buildings.
 
     \quotefromfile demos/osmbuildings/Main.qml
     \skipto id: chunkModelBuilding
@@ -95,17 +129,14 @@
     \printuntil ]
     \printuntil }
 
-    To render buildings parts e.g rooftop and body of the building with one draw call,
-    it uses a custom shader to render building chunks.
+    To render building parts such as rooftops with one draw call,
+    a custom shader is used.
 
     \quotefromfile demos/osmbuildings/customshaderbuildings.frag
     \skipto SPDX-License-Identifier
     \printuntil }
     \printuntil }
 
-    To understand the application better, browse through its code using
-    Qt Creator.
-
     \include examples-run.qdocinc
 
     \sa {QML Applications}