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>

15 files changed, 117 insertions, 382 deletions

diff --git a/src/imports/location/location.cpp b/src/imports/location/location.cpp
index 59724305..8621524e 100644
--- a/src/imports/location/location.cpp
+++ b/src/imports/location/location.cpp
@@ -115,7 +115,6 @@ public:
             qmlRegisterType<QDeclarativeGeoRouteModel               >(uri, major, minor, "RouteModel");
             qmlRegisterType<QDeclarativeGeoRouteQuery               >(uri, major, minor, "RouteQuery");
             qmlRegisterType<QDeclarativeGeoRoute                    >(uri, major, minor, "Route"); // data type
-            qmlRegisterType<QDeclarativeGeoRouteSegment             >(uri, major, minor, "RouteSegment");
             qmlRegisterUncreatableType<QGeoMapPinchEvent >(uri, major, minor, "MapPinchEvent",
                                         QStringLiteral("(Map)PinchEvent is not intended instantiable by developer."));
             qmlRegisterUncreatableType<QQuickGeoMapGestureArea>(uri, major, minor, "MapGestureArea",
diff --git a/src/imports/location/location.h b/src/imports/location/location.h
index 4f682626..ba3743ea 100644
--- a/src/imports/location/location.h
+++ b/src/imports/location/location.h
@@ -52,6 +52,7 @@
 //
 
 #include <QGeoManeuver>
+#include <QGeoRouteSegment>
 
 #include <QtLocation/private/qgeomaptype_p.h>
 
@@ -73,6 +74,13 @@ namespace QGeoManeuverForeignNamespace
     QML_NAMED_ELEMENT(RouteManeuver)
 };
 
+struct QGeoRouteSegmentForeign
+{
+    Q_GADGET
+    QML_FOREIGN(QGeoRouteSegment)
+    QML_NAMED_ELEMENT(routeSegment)
+};
+
 QT_END_NAMESPACE
 
 #endif // QTLOCATION_QMLTYPES_H
diff --git a/src/location/CMakeLists.txt b/src/location/CMakeLists.txt
index d120dacb..68b0dd2c 100644
--- a/src/location/CMakeLists.txt
+++ b/src/location/CMakeLists.txt
@@ -129,8 +129,6 @@ qt_internal_add_module(Location
         declarativemaps/qdeclarativegeoroute.cpp declarativemaps/qdeclarativegeoroute_p.h
         declarativemaps/qdeclarativegeoroutemodel.cpp declarativemaps/qdeclarativegeoroutemodel_p.h
         declarativemaps/qgeosimplify.cpp declarativemaps/qgeosimplify_p.h
-        declarativemaps/qdeclarativegeoroutesegment.cpp
-        declarativemaps/qdeclarativegeoroutesegment_p.h
         declarativeplaces/qdeclarativecategory.cpp
         declarativeplaces/qdeclarativecategory_p.h
         declarativeplaces/qdeclarativecontactdetail.cpp
diff --git a/src/location/declarativemaps/qdeclarativegeoroute.cpp b/src/location/declarativemaps/qdeclarativegeoroute.cpp
index ae61b828..104b87b7 100644
--- a/src/location/declarativemaps/qdeclarativegeoroute.cpp
+++ b/src/location/declarativemaps/qdeclarativegeoroute.cpp
@@ -63,7 +63,7 @@ QT_BEGIN_NAMESPACE
     as the length the route, the estimated travel time for the route,
     and enough information to render a basic image of the route on a map.
 
-    The QGeoRoute object also contains a list of \l RouteSegment objects which
+    The QGeoRoute object also contains a list of \l routeSegment objects which
     describe subsections of the route in greater detail.
 
     The primary means of acquiring Route objects is \l RouteModel.
@@ -93,33 +93,6 @@ QDeclarativeGeoRoute::QDeclarativeGeoRoute(const QGeoRoute &route, QObject *pare
 
 QDeclarativeGeoRoute::~QDeclarativeGeoRoute() {}
 
-void QDeclarativeGeoRoute::initSegments(unsigned int lastIndex) // -1  turns it into unsigned int max
-{
-    if (!segmentsDirty_)
-        return;
-
-    const bool isLeg = qobject_cast<QDeclarativeGeoRoute *>(parent());
-    QGeoRouteSegment segment = route_.firstRouteSegment();
-    unsigned int idx = 0;
-    unsigned int initialListSize = static_cast<unsigned int>(segments_.size());
-    while (segment.isValid()) {
-        if (idx >= initialListSize) {
-            QDeclarativeGeoRouteSegment *routeSegment = new QDeclarativeGeoRouteSegment(segment, this);
-            QQmlEngine::setContextForObject(routeSegment, QQmlEngine::contextForObject(this));
-            segments_.append(routeSegment);
-        }
-        if (isLeg && segment.isLegLastSegment()) {
-            segmentsDirty_ = false;
-            return;
-        }
-        ++idx;
-        segment = segment.nextRouteSegment();
-        if (idx > lastIndex && segment.isValid()) // Do not clean segmentsDirty_ if there are still segments to initialize
-            return;
-    }
-    segmentsDirty_ = false;
-}
-
 /*!
     \internal
 */
@@ -224,65 +197,26 @@ void QDeclarativeGeoRoute::setPath(const QJSValue &value)
 }
 
 /*!
-    \qmlproperty list<RouteSegment> QtLocation::Route::segments
+    \qmlproperty list<routeSegment> QtLocation::Route::segments
 
-    Read-only property which holds the list of \l RouteSegment objects of this route.
+    Read-only property which holds the list of \l routeSegment objects of this route.
 
     To access individual segments you can use standard list accessors: 'segments.length'
     indicates the number of objects and 'segments[index starting from zero]' gives
     the actual objects.
 
-    \sa RouteSegment
-*/
-
-QQmlListProperty<QDeclarativeGeoRouteSegment> QDeclarativeGeoRoute::segments()
-{
-    return QQmlListProperty<QDeclarativeGeoRouteSegment>(this, 0, segments_append, segments_count,
-                                                         segments_at, segments_clear);
-}
-
-/*!
-    \internal
-*/
-void QDeclarativeGeoRoute::segments_append(QQmlListProperty<QDeclarativeGeoRouteSegment> *prop,
-                                           QDeclarativeGeoRouteSegment *segment)
-{
-    QDeclarativeGeoRoute *declRoute = static_cast<QDeclarativeGeoRoute *>(prop->object);
-    declRoute->initSegments();
-    declRoute->appendSegment(segment);
-}
-
-/*!
-    \internal
+    \sa routeSegment
 */
-qsizetype QDeclarativeGeoRoute::segments_count(QQmlListProperty<QDeclarativeGeoRouteSegment> *prop)
-{
-    QDeclarativeGeoRoute *declRoute = static_cast<QDeclarativeGeoRoute *>(prop->object);
-    return declRoute->segmentsCount();
-}
 
-/*!
-    \internal
-*/
-QDeclarativeGeoRouteSegment *QDeclarativeGeoRoute::segments_at(QQmlListProperty<QDeclarativeGeoRouteSegment> *prop, qsizetype index)
-{
-    QDeclarativeGeoRoute *declRoute = static_cast<QDeclarativeGeoRoute *>(prop->object);
-    declRoute->initSegments(index); // init only what's needed.
-    return declRoute->segments_.at(index);
-}
-
-/*!
-    \internal
-*/
-void QDeclarativeGeoRoute::segments_clear(QQmlListProperty<QDeclarativeGeoRouteSegment> *prop)
+QList<QGeoRouteSegment> QDeclarativeGeoRoute::segments()
 {
-    static_cast<QDeclarativeGeoRoute *>(prop->object)->clearSegments();
+    return segments_;
 }
 
 /*!
     \internal
 */
-void QDeclarativeGeoRoute::appendSegment(QDeclarativeGeoRouteSegment *segment)
+void QDeclarativeGeoRoute::appendSegment(const QGeoRouteSegment &segment)
 {
     segments_.append(segment);
 }
@@ -300,7 +234,7 @@ void QDeclarativeGeoRoute::clearSegments()
 
     Returns the number of segments in the route
 
-    \sa RouteSegment
+    \sa routeSegment
 
     \since 5.11
 */
diff --git a/src/location/declarativemaps/qdeclarativegeoroute_p.h b/src/location/declarativemaps/qdeclarativegeoroute_p.h
index 4e64949b..a43e9d4d 100644
--- a/src/location/declarativemaps/qdeclarativegeoroute_p.h
+++ b/src/location/declarativemaps/qdeclarativegeoroute_p.h
@@ -52,12 +52,13 @@
 //
 
 #include <QtLocation/private/qlocationglobal_p.h>
-#include <QtLocation/private/qdeclarativegeoroutesegment_p.h>
 
 #include <QtCore/QObject>
-#include <QtQml/QQmlListProperty>
+#include <QtCore/QList>
 #include <QtQml/QQmlPropertyMap>
+#include <QtQml/QJSValue>
 #include <QtLocation/QGeoRoute>
+#include <QtLocation/QGeoRouteSegment>
 
 Q_MOC_INCLUDE(<QtLocation/private/qdeclarativegeoroutemodel_p.h>)
 
@@ -72,7 +73,7 @@ class Q_LOCATION_PRIVATE_EXPORT QDeclarativeGeoRoute : public QObject
     Q_PROPERTY(int travelTime READ travelTime CONSTANT)
     Q_PROPERTY(qreal distance READ distance CONSTANT)
     Q_PROPERTY(QJSValue path READ path WRITE setPath NOTIFY pathChanged)
-    Q_PROPERTY(QQmlListProperty<QDeclarativeGeoRouteSegment> segments READ segments CONSTANT)
+    Q_PROPERTY(QList<QGeoRouteSegment> segments READ segments CONSTANT)
     Q_PROPERTY(QDeclarativeGeoRouteQuery *routeQuery READ routeQuery REVISION 11)
     Q_PROPERTY(QList<QObject *> legs READ legs CONSTANT REVISION 12)
     Q_PROPERTY(QObject *extendedAttributes READ extendedAttributes CONSTANT REVISION 13)
@@ -89,9 +90,9 @@ public:
     QJSValue path() const;
     void setPath(const QJSValue &value);
 
-    QQmlListProperty<QDeclarativeGeoRouteSegment> segments();
+    QList<QGeoRouteSegment> segments();
 
-    void appendSegment(QDeclarativeGeoRouteSegment *segment);
+    void appendSegment(const QGeoRouteSegment &segment);
     void clearSegments();
 
     int segmentsCount() const;
@@ -106,19 +107,12 @@ Q_SIGNALS:
     void pathChanged();
 
 private:
-    static void segments_append(QQmlListProperty<QDeclarativeGeoRouteSegment> *prop, QDeclarativeGeoRouteSegment *segment);
-    static qsizetype segments_count(QQmlListProperty<QDeclarativeGeoRouteSegment> *prop);
-    static QDeclarativeGeoRouteSegment *segments_at(QQmlListProperty<QDeclarativeGeoRouteSegment> *prop, qsizetype index);
-    static void segments_clear(QQmlListProperty<QDeclarativeGeoRouteSegment> *prop);
-
-    void initSegments(unsigned int lastIndex = ~0U);
     QList<QGeoCoordinate> routePath();
 
     QGeoRoute route_;
     QDeclarativeGeoRouteQuery *routeQuery_ = nullptr;
-    QList<QDeclarativeGeoRouteSegment *> segments_;
+    QList<QGeoRouteSegment> segments_;
     QList<QObject *> legs_;
-    bool segmentsDirty_ = true;
     QQmlPropertyMap *m_extendedAttributes = nullptr;
 
     friend class QDeclarativeRouteMapItem;
diff --git a/src/location/declarativemaps/qdeclarativegeoroutesegment.cpp b/src/location/declarativemaps/qdeclarativegeoroutesegment.cpp
deleted file mode 100644
index 7a910f85..00000000
--- a/src/location/declarativemaps/qdeclarativegeoroutesegment.cpp
+++ /dev/null
@@ -1,164 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the QtLocation module of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:LGPL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Lesser General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU Lesser
-** General Public License version 3 as published by the Free Software
-** Foundation and appearing in the file LICENSE.LGPL3 included in the
-** packaging of this file. Please review the following information to
-** ensure the GNU Lesser General Public License version 3 requirements
-** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
-**
-** GNU General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU
-** General Public License version 2.0 or (at your option) the GNU General
-** Public license version 3 or any later version approved by the KDE Free
-** Qt Foundation. The licenses are as published by the Free Software
-** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
-** included in the packaging of this file. Please review the following
-** information to ensure the GNU General Public License requirements will
-** be met: https://www.gnu.org/licenses/gpl-2.0.html and
-** https://www.gnu.org/licenses/gpl-3.0.html.
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-#include "qdeclarativegeoroutesegment_p.h"
-
-#include <QtQml/QQmlEngine>
-#include <QtQml/private/qqmlengine_p.h>
-#include <QtPositioning/QGeoCoordinate>
-
-QT_BEGIN_NAMESPACE
-
-/*!
-    \qmltype RouteSegment
-    \instantiates QDeclarativeGeoRouteSegment
-    \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 RouteManeuvers associated with
-    the end of the route segment.
-
-    RouteSegment instances 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
-*/
-
-QDeclarativeGeoRouteSegment::QDeclarativeGeoRouteSegment(QObject *parent)
-    : QObject(parent)
-{
-}
-
-QDeclarativeGeoRouteSegment::QDeclarativeGeoRouteSegment(const QGeoRouteSegment &segment,
-                                                         QObject *parent)
-    : QObject(parent),
-      segment_(segment)
-{
-}
-
-QDeclarativeGeoRouteSegment::~QDeclarativeGeoRouteSegment() {}
-
-/*!
-    \qmlproperty int QtLocation::RouteSegment::travelTime
-
-    Read-only property which holds the estimated amount of time it will take to
-    traverse this segment, in seconds.
-
-*/
-
-int QDeclarativeGeoRouteSegment::travelTime() const
-{
-    return segment_.travelTime();
-}
-
-/*!
-    \qmlproperty real QtLocation::RouteSegment::distance
-
-    Read-only property which holds the distance covered by this segment of the route, in meters.
-
-*/
-
-qreal QDeclarativeGeoRouteSegment::distance() const
-{
-    return segment_.distance();
-}
-
-/*!
-    \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.
-*/
-
-QGeoManeuver QDeclarativeGeoRouteSegment::maneuver() const
-{
-    return segment_.maneuver();
-}
-
-/*!
-    \qmlproperty list<coordinate> QtLocation::RouteSegment::path
-
-    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
-*/
-
-QJSValue QDeclarativeGeoRouteSegment::path() const
-{
-    QQmlContext *context = QQmlEngine::contextForObject(parent());
-    QQmlEngine *engine = context->engine();
-    QV4::ExecutionEngine *v4 = QQmlEnginePrivate::getV4Engine(engine);
-
-    QV4::Scope scope(v4);
-    QV4::Scoped<QV4::ArrayObject> pathArray(scope, v4->newArrayObject(segment_.path().length()));
-    for (int i = 0; i < segment_.path().length(); ++i) {
-        const QGeoCoordinate &c = segment_.path().at(i);
-
-        QV4::ScopedValue cv(scope, v4->fromVariant(QVariant::fromValue(c)));
-        pathArray->put(i, cv);
-    }
-
-    return QJSValuePrivate::fromReturnedValue(pathArray.asReturnedValue());
-}
-
-QT_END_NAMESPACE
diff --git a/src/location/declarativemaps/qdeclarativegeoroutesegment_p.h b/src/location/declarativemaps/qdeclarativegeoroutesegment_p.h
deleted file mode 100644
index a531b022..00000000
--- a/src/location/declarativemaps/qdeclarativegeoroutesegment_p.h
+++ /dev/null
@@ -1,88 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the QtLocation module of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:LGPL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Lesser General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU Lesser
-** General Public License version 3 as published by the Free Software
-** Foundation and appearing in the file LICENSE.LGPL3 included in the
-** packaging of this file. Please review the following information to
-** ensure the GNU Lesser General Public License version 3 requirements
-** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
-**
-** GNU General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU
-** General Public License version 2.0 or (at your option) the GNU General
-** Public license version 3 or any later version approved by the KDE Free
-** Qt Foundation. The licenses are as published by the Free Software
-** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
-** included in the packaging of this file. Please review the following
-** information to ensure the GNU General Public License requirements will
-** be met: https://www.gnu.org/licenses/gpl-2.0.html and
-** https://www.gnu.org/licenses/gpl-3.0.html.
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-#ifndef QDECLARATIVEGEOROUTESEGMENT_H
-#define QDECLARATIVEGEOROUTESEGMENT_H
-
-//
-//  W A R N I N G
-//  -------------
-//
-// This file is not part of the Qt API.  It exists purely as an
-// implementation detail.  This header file may change from version to
-// version without notice, or even be removed.
-//
-// We mean it.
-//
-
-#include <QtLocation/private/qlocationglobal_p.h>
-
-#include <QtCore/QObject>
-#include <QtQml/qjsvalue.h>
-#include <QtLocation/QGeoRouteSegment>
-#include <QtLocation/QGeoManeuver>
-
-QT_BEGIN_NAMESPACE
-
-class Q_LOCATION_PRIVATE_EXPORT QDeclarativeGeoRouteSegment : public QObject
-{
-    Q_OBJECT
-
-    Q_PROPERTY(int travelTime READ travelTime CONSTANT)
-    Q_PROPERTY(qreal distance READ distance CONSTANT)
-    Q_PROPERTY(QJSValue path READ path CONSTANT)
-    Q_PROPERTY(QGeoManeuver maneuver READ maneuver CONSTANT)
-
-public:
-    explicit QDeclarativeGeoRouteSegment(QObject *parent = 0);
-    QDeclarativeGeoRouteSegment(const QGeoRouteSegment &segment, QObject *parent = 0);
-    ~QDeclarativeGeoRouteSegment();
-
-    int travelTime() const;
-    qreal distance() const;
-    QJSValue path() const;
-    QGeoManeuver maneuver() const;
-
-private:
-    QGeoRouteSegment segment_;
-};
-
-QT_END_NAMESPACE
-
-#endif
diff --git a/src/location/doc/snippets/declarative/routing.qml b/src/location/doc/snippets/declarative/routing.qml
index 3027b22b..c09913c6 100644
--- a/src/location/doc/snippets/declarative/routing.qml
+++ b/src/location/doc/snippets/declarative/routing.qml
@@ -100,7 +100,7 @@ Item {
             Text { text: hasManeuver ? modelData.maneuver.instructionText : "" }
     //! [Route Maneuver List2]
             property routeManeuver routeManeuver: modelData.maneuver
-            property RouteSegment routeSegment: modelData
+            property routeSegment routeSegment: modelData
 
             //! [routeManeuver]
             Text {
@@ -109,11 +109,11 @@ Item {
             }
             //! [routeManeuver]
 
-            //! [RouteSegment]
+            //! [routeSegment]
             Text {
                 text: "Segment distance " + routeSegment.distance + " meters, " + routeSegment.path.length + " points."
             }
-            //! [RouteSegment]
+            //! [routeSegment]
     //! [Route Maneuver List3]
         }
     }
diff --git a/src/location/doc/src/maps.qdoc b/src/location/doc/src/maps.qdoc
index edddbb4f..f633145d 100644
--- a/src/location/doc/src/maps.qdoc
+++ b/src/location/doc/src/maps.qdoc
@@ -159,7 +159,7 @@ will enable access to geocoding translation services and thus data to display.
 Routing is the determination of a navigable path from one point to another on
 a map. Given a map that is aware of features that aid or hinder navigation, such as
 bridges, waterways and so on, a series of segments that make
-up the journey can be constructed. If these \l {RouteSegment}s are simple then we can
+up the journey can be constructed. If these \l {routeSegment}s are simple then we can
 add navigation information at the connecting points, \l {routeManeuver}s,
 between the segments.
 
@@ -169,7 +169,7 @@ between the segments.
         \li \l{QtLocation::Route}{Route}
         \li The entire path to be navigated.
     \row
-        \li \l{QtLocation::RouteSegment}{RouteSegment}
+        \li \l{QtLocation::routeSegment}{routeSegment}
         \li The individual components of a route.
     \row
         \li \l{QtLocation::routeManeuver}{routeManeuver}
diff --git a/src/location/doc/src/qml-maps.qdoc b/src/location/doc/src/qml-maps.qdoc
index 2b160487..f342c264 100644
--- a/src/location/doc/src/qml-maps.qdoc
+++ b/src/location/doc/src/qml-maps.qdoc
@@ -129,7 +129,7 @@ a \e maneuver contains navigational information, for example "turn right now".
 
 To find a suitable route we will need to use a \l RouteQuery to define the
 selection criteria and adding any required waypoints.
-The \l RouteModel should return a list of \l {RouteSegment}s that defines the
+The \l RouteModel should return a list of \l {routeSegment}s that defines the
 route to the destination complete with navigation advice at the joins between
 segments, called \l {routeManeuver}s
 
diff --git a/src/location/doc/src/qtlocation-qml.qdoc b/src/location/doc/src/qtlocation-qml.qdoc
index 90f19c5a..05d5d763 100644
--- a/src/location/doc/src/qtlocation-qml.qdoc
+++ b/src/location/doc/src/qtlocation-qml.qdoc
@@ -43,7 +43,7 @@
 
     To perform navigation we need \l {Route}s from start to destination.
     These routes are made up of segments, where each \l {QtLocation::}
-    {RouteSegment} can be considered a navigation subtask; for example,
+    {routeSegment} can be considered a navigation subtask; for example,
     "drive 100 meters", or "turn left". The beginning and end of each
     segment is a \e waypoint, that is, one part of the journey.
 
@@ -69,7 +69,7 @@
             and so on.
 
         \li The \l [QML] Route is be determined by a \e plugin, with each
-            \l [QML] RouteSegment holding the navigation instructions,
+            \l [QML] routeSegment holding the navigation instructions,
             guided by the continuously updated current \l [QML] Location.
 
     \endlist
diff --git a/src/location/labs/qdeclarativenavigator.cpp b/src/location/labs/qdeclarativenavigator.cpp
index d4374719..8aad5f20 100644
--- a/src/location/labs/qdeclarativenavigator.cpp
+++ b/src/location/labs/qdeclarativenavigator.cpp
@@ -36,7 +36,6 @@
 #include <QtLocation/private/qgeomapparameter_p.h>
 #include <QtLocation/private/qdeclarativegeoroute_p.h>
 #include <QtLocation/private/qdeclarativegeoroutemodel_p.h>
-#include <QtLocation/private/qdeclarativegeoroutesegment_p.h>
 #include <QtLocation/qgeoserviceprovider.h>
 #include <QtPositioningQuick/private/qdeclarativepositionsource_p.h>
 #include <QtQml/qqmlinfo.h>
@@ -622,12 +621,12 @@ QDeclarativeNavigationBasicDirections::QDeclarativeNavigationBasicDirections(QDe
             so the \l {RouteLeg::}{overallRoute} property of \c currentRouteLeg
             holds the same route as \c currentRoute.
         \li The \c currentSegment property holds the index of the current
-            RouteSegment in the \c currentRoute.
+            routeSegment in the \c currentRoute.
         \li The \c alternativeRoutes property holds the list of alternative routes provided by
             the engine. If no alternative routes are present, the model will be empty.
     \endlist
 
-    \sa directions.waypointReached(), directions.destinationReached(), Route, RouteLeg, RouteSegment, Waypoint
+    \sa directions.waypointReached(), directions.destinationReached(), Route, RouteLeg, routeSegment, Waypoint
 */
 
 /*!
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();
diff --git a/tests/auto/declarative_location_core/tst_routing.qml b/tests/auto/declarative_location_core/tst_routing.qml
index 2540a54c..fe3a2dbd 100644
--- a/tests/auto/declarative_location_core/tst_routing.qml
+++ b/tests/auto/declarative_location_core/tst_routing.qml
@@ -73,11 +73,11 @@ Item {
     property variant ntr: QtPositioning.coordinate(3, 3)
 
     property variant unitBox: QtPositioning.rectangle(tl, br)
+    property routeSegment emptySegment
 
     Route {id: emptyRoute}
     TestCase {
         name: "RouteManeuver RouteSegment and MapRoute"
-        RouteSegment {id: emptySegment}
 
         // TODO enable when we have map route
         //MapRoute {id: emptyMapRoute}