Remove QDeclarativeGeoRouteSegment wrapper

Register the QGeoRouteSegment gadget type directly as the routeSegment
QML type (via a Foreign), and use it in QDeclarativeGeoRoute.

The type is now uncreatable. It wasn't in 5.15, but since there is no
setter-API that is exposed to QML, there is no reason to have it be a
creatable type. Adjust the QML test to declare a property of type
routeSegment instead.

Move the QML type documentation into QGeoRouteSegment, and document the
corresponding C++ properties via \property. Unify the language a bit,
and follow up on the rename from RouteSegment to routeSegment.

Pick-to: 6.2
Change-Id: I1ebae0c1a9d056aa59510a3ab539b1d8bce8c6c7
Reviewed-by: Ulf Hermann <ulf.hermann@qt.io>
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>

2 files changed, 83 insertions, 28 deletions

diff --git a/src/location/maps/qgeomaneuver.cpp b/src/location/maps/qgeomaneuver.cpp
index a841e543..b8bb4222 100644
--- a/src/location/maps/qgeomaneuver.cpp
+++ b/src/location/maps/qgeomaneuver.cpp
@@ -81,9 +81,9 @@ QT_DEFINE_QSDP_SPECIALIZATION_DTOR(QGeoManeuverPrivate)
     \since QtLocation 5.5
 
     \brief The routeManeuver type represents the information relevant to the
-    point at which two RouteSegments meet.
+    point at which two routeSegments meet.
 
-    RouteSegment instances can be thought of as edges on a routing
+    Instances of routeSegment can be thought of as edges on a routing
     graph, with routeManeuver instances as optional labels attached to the
     vertices of the graph.
 
diff --git a/src/location/maps/qgeoroutesegment.cpp b/src/location/maps/qgeoroutesegment.cpp
index 5eba28cd..e967183d 100644
--- a/src/location/maps/qgeoroutesegment.cpp
+++ b/src/location/maps/qgeoroutesegment.cpp
@@ -72,6 +72,36 @@ QT_DEFINE_QESDP_SPECIALIZATION_DTOR(QGeoRouteSegmentPrivate)
 */
 
 /*!
+    \qmltype routeSegment
+    \inqmlmodule QtLocation
+    \ingroup qml-QtLocation5-routing
+    \since QtLocation 5.5
+
+    \brief The routeSegment type represents a segment of a Route.
+
+    A routeSegment instance has information about the physical layout
+    of the route segment, the length of the route and estimated time required
+    to traverse the route segment and optional \l {routeManeuver}s associated with
+    the end of the route segment.
+
+    Instances of routeSegment can be thought of as edges on a routing
+    graph, with routeManeuver instances as optional labels attached to the
+    vertices of the graph.
+
+    The primary means of acquiring Route objects is via Routes via \l RouteModel.
+
+    \section1 Example
+
+    The following QML snippet demonstrates how to print information about a
+    route segment:
+
+    \snippet declarative/routing.qml QtQuick import
+    \snippet declarative/maps.qml QtLocation import
+    \codeline
+    \snippet declarative/routing.qml routeSegment
+*/
+
+/*!
     Constructs an invalid route segment object.
 
     The route segment will remain invalid until one of setNextRouteSegment(),
@@ -181,8 +211,17 @@ QGeoRouteSegment QGeoRouteSegment::nextRouteSegment() const
 }
 
 /*!
-    Sets the estimated amount of time it will take to traverse this segment of
-    the route, in seconds, to \a secs.
+    \qmlproperty int QtLocation::routeSegment::travelTime
+
+    Read-only property which holds the estimated amount of time it will take to
+    traverse this segment, in seconds.
+
+*/
+
+/*!
+    \property QGeoRouteSegment::travelTime
+    \brief the estimated amount of time, in seconds, that it will take to
+    traverse this segment.
 */
 void QGeoRouteSegment::setTravelTime(int secs)
 {
@@ -190,17 +229,21 @@ void QGeoRouteSegment::setTravelTime(int secs)
     d_ptr->setTravelTime(secs);
 }
 
-/*!
-    Returns the estimated amount of time it will take to traverse this segment
-    of the route, in seconds.
-*/
 int QGeoRouteSegment::travelTime() const
 {
     return d_ptr->travelTime();
 }
 
 /*!
-    Sets the distance covered by this segment of the route, in meters, to \a distance.
+    \qmlproperty real QtLocation::routeSegment::distance
+
+    Read-only property which holds the distance covered by this segment of
+    the route, in meters.
+*/
+
+/*!
+    \property QGeoRouteSegment::distance
+    \brief the distance covered by this segment of the route, in meters.
 */
 void QGeoRouteSegment::setDistance(qreal distance)
 {
@@ -208,32 +251,37 @@ void QGeoRouteSegment::setDistance(qreal distance)
     d_ptr->setDistance(distance);
 }
 
-/*!
-    Returns the distance covered by this segment of the route, in meters.
-*/
 qreal QGeoRouteSegment::distance() const
 {
     return d_ptr->distance();
 }
 
 /*!
-    Sets the geometric shape of this segment of the route to \a path.
+    \qmlproperty list<coordinate> QtLocation::routeSegment::path
 
-    The coordinates in \a path should be listed in the order in which they
-    would be traversed by someone traveling along this segment of the route.
+    Read-only property which holds the geographical coordinates of this segment.
+    Coordinates are listed in the order in which they would be traversed by someone
+    traveling along this segment of the route.
+
+    To access individual segments you can use standard list accessors: 'path.length'
+    indicates the number of objects and 'path[index starting from zero]' gives
+    the actual object.
+
+    \sa QtPositioning::coordinate
 */
-void QGeoRouteSegment::setPath(const QList<QGeoCoordinate> &path)
-{
-    d_ptr->setValid(true);
-    d_ptr->setPath(path);
-}
 
 /*!
-    Returns the geometric shape of this route segment of the route.
+    \property QGeoRouteSegment::path
+    \brief the geometric shape of this route segment of the route.
 
     The coordinates should be listed in the order in which they
     would be traversed by someone traveling along this segment of the route.
 */
+void QGeoRouteSegment::setPath(const QList<QGeoCoordinate> &path)
+{
+    d_ptr->setValid(true);
+    d_ptr->setPath(path);
+}
 
 QList<QGeoCoordinate> QGeoRouteSegment::path() const
 {
@@ -241,7 +289,20 @@ QList<QGeoCoordinate> QGeoRouteSegment::path() const
 }
 
 /*!
-    Sets the maneuver for this route segment to \a maneuver.
+    \qmlproperty RouteManeuver QtLocation::routeSegment::maneuver
+
+    Read-only property which holds the maneuver for this route segment.
+
+    Will return invalid maneuver if no information has been attached to the endpoint
+    of this route segment.
+*/
+
+/*!
+    \property QGeoRouteSegment::maneuver
+    \brief the maneuver for this route segment.
+
+    Holds an invalid QGeoManeuver if no information has been attached
+    to the starting point of this route segment.
 */
 void QGeoRouteSegment::setManeuver(const QGeoManeuver &maneuver)
 {
@@ -249,12 +310,6 @@ void QGeoRouteSegment::setManeuver(const QGeoManeuver &maneuver)
     d_ptr->setManeuver(maneuver);
 }
 
-/*!
-    Returns the maneuver for this route segment.
-
-    Will return an invalid QGeoManeuver if no information has been attached
-    to the starting point of this route segment.
-*/
 QGeoManeuver QGeoRouteSegment::maneuver() const
 {
     return d_ptr->maneuver();