Fix QtLocation documentation

This moves the docs to its proper place and fixes content as well as
broken links.

There are still some warnings left.

Change-Id: Ie83086f4feabab5f3b3d6c92eb6b401a5ff43e29
Reviewed-by: Alex <alexander.blasche@digia.com>

1 files changed, 216 insertions, 0 deletions

diff --git a/src/location/doc/src/qml-maps.qdoc b/src/location/doc/src/qml-maps.qdoc
new file mode 100644
index 00000000..45cf82f4
--- /dev/null
+++ b/src/location/doc/src/qml-maps.qdoc
@@ -0,0 +1,216 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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 Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \group qml-QtLocation5-maps
+    \title QML Maps Plugin
+    QML Support for the Qt Location API.
+*/
+
+
+/*!
+\page qml-location5-maps.html
+\title QML Maps
+
+\brief Maps deals with maps, their contents and navigation.
+
+\section1 Overview
+
+The \l Map type allows the display of a map and placing objects within the map.
+Various points of interest can be defined and added to the map for display.
+Also the \l Map has features to control how the map is displayed. With the
+Map item you can center the map, zoom, pinch and make the item flickable.
+
+The places to be added to the map are
+\l {Maps and Navigation (QML)#Putting Objects on a Map (Map Overlay Objects)}{MapItems}. The item's
+position is defined by a \l {coordinate}{coordinate} which includes latitude,
+longitude and altitude.  The item is then displayed automatically after it is added to the Map.
+Interaction with the added items, and the \l Map itself, is handled by \l MapMouseArea when items
+are added as children of the
+\l {Maps and Navigation (QML)#Putting Objects on a Map (Map Overlay Objects)}{MapItems} or \l Map.
+
+\section2 Position
+
+The basic piece of position information is the \l {coordinate}.  A
+coordinate encapsulates data for the latitude, longitude and altitude of the location.  Altitude is
+in meters. It also has a method to determine distance to another
+\l {coordinate}.  The \l {coordinate} type may
+also be held within a \l {QtLocation5::Location}{Location} element, this will also have information
+on a bounding box size to determine sufficient proximity to the location and a location address.
+
+\section2 Geocoding
+
+\l {http://en.wikipedia.org/wiki/Geocoding}{Geocoding} is the derivation of
+geographical coordinates (latitude and longitude) from other geographical references
+to the locations. For example, this can be a street address. Reverse geocoding is also possible with
+a street address being used to determine a geographical coordinate. Geocoding
+is performed by using the \l GeoCodeModel type.
+
+The following code examples are a small part of the \c map component in the
+\l {Map Viewer (QML)}{Map Viewer (QML)} example. The snippets
+demonstrate the declaration of the \l GeocodeModel component.
+
+In the snippet we see that the \c geocodeModel property contains the plugin
+and two signal handlers. One for changes in status (\c onStatusChanged ) and
+the other to update the centering of the Map object (\c onLocationsChanged ).
+
+\snippet mapviewer/content/map/MapComponent.qml geocodemodel0
+\snippet mapviewer/content/map/MapComponent.qml geocodemodel0 body
+\snippet mapviewer/content/map/MapComponent.qml geocodemodel1
+\codeline
+\snippet mapviewer/content/map/MapComponent.qml geocodeview
+
+These geocoding features are called from a higher level piece of code. In this
+snippet we see an \c onGoButtonClicked signal handler that extracts the address
+from the user interface and then creates a query for the \l GeocodeModel to
+process and determine the geographical coordinates.
+
+\snippet mapviewer/mapviewer.qml geocode1
+
+
+\section2 Navigation
+
+A very important function of the \l Map type is navigation
+from one place to a destination with possible waypoints along the route. The
+route will be divided up into a series of segments. At the end of each segment
+is a vertex called a \e maneuver. The \e segments contain information about
+the time and distance to the end of the segment. The \e maneuvers contain information
+about what to do next, how to get onto the next segment, if there is one. So
+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
+route to the destination complete with navigation advice at the joins between
+segments, called \l {RouteManeuver}s
+
+There are many options that you can add to the query to narrow the criteria.
+The \l RouteQuery properties can include
+
+\table 60%
+    \row
+        \li \l {RouteQuery::}{numberAlternativeRoutes}
+        \li The number of alternative routes
+    \row
+        \li \l {RouteQuery::}{travelModes}
+        \li Travel modes
+    \row
+        \li \l {RouteQuery::}{routeOptimizations}
+        \li Required route optimizations
+    \row
+        \li \l {RouteQuery::}{segmentDetail}
+        \li Level of detail in segments
+    \row
+        \li \l {RouteQuery::}{maneuverDetail}
+        \li Level of detail in maneuvers between segments
+    \row
+        \li \l {RouteQuery::}{waypoints}
+        \li A list of waypoints
+    \row
+        \li \l {RouteQuery::}{excludedAreas}
+        \li A list of excluded areas that the route must not cross
+    \row
+        \li \l {RouteQuery::}{featureTypes}
+        \li Relevant map features, for example highway, ferry
+\endtable
+
+
+In the following example a default RouteQuery is declared, later to be defined
+by some user input, and used in \c routeModel as the query. The \c routeInfoModel
+is a \l {Models and Views in Qt Quick#ListModel}{ListModel} that can be updated using an
+\c update() function that we will look at later.
+
+\snippet mapviewer/content/map/MapComponent.qml routemodel0
+\codeline
+\snippet mapviewer/content/map/MapComponent.qml routemodel1
+\codeline
+\snippet mapviewer/content/map/MapComponent.qml routemodel2
+\snippet mapviewer/content/map/MapComponent.qml routemodel3
+
+The user enters, via a dialog, some information such as the starting point
+of the route, some waypoints and the destination. All of these locations are
+waypoints so the locations from start to finish will be entered as a sequence
+of waypoints. Then other query properties can be set that may be specific to
+this trip.
+
+\snippet mapviewer/mapviewer.qml routerequest0
+\codeline
+\snippet mapviewer/mapviewer.qml routerequest0 feature weight
+\codeline
+\snippet mapviewer/mapviewer.qml routerequest1
+\snippet mapviewer/mapviewer.qml routedialog1
+
+The \c routeInfoModel \l {Models and Views in Qt Quick#ListModel}{ListModel} is used to grab the
+results of the query and construct a suitable list for display.  The
+\l {Models and Views in Qt Quick#ListModel}{ListModel} \c routeInfoModel contains an \c update()
+function that loops through the segments extracting the segment length, instruction text and
+distance to the next instruction.  The extracted data is formatted for display as it is retrieved.
+
+\snippet mapviewer/content/map/MapComponent.qml routeinfomodel
+\codeline
+\snippet mapviewer/content/map/MapComponent.qml routeview
+
+For more information on the example see the \l {Map Viewer (QML)}{Map Viewer (QML)} example.
+
+
+\section2  Zoom, Pinch and Flickable
+
+The \l Map item also supports user interface interactions with the map using
+tactile and mouse gestures. That is features such as swiping to pan,
+pinching to zoom.
+
+Enabling and configuring pinch and flickable is easy within the \l Map type.
+
+\snippet mapviewer/content/map/MapComponent.qml top
+\snippet mapviewer/content/map/MapComponent.qml end
+
+Zoom can also be controlled by other objects like sliders, as shown in the
+example, by implementing the \c onValueChanged handler to update the Map
+\l {QtLocation5::Map::}{zoomLevel}.
+
+\section1 Types
+
+\section3 Positioning
+\annotatedlist qml-QtLocation5-positioning
+
+\section3 Maps
+\annotatedlist qml-QtLocation5-maps
+
+\section3 Geocoding
+\annotatedlist qml-QtLocation5-geocoding
+
+\section3 Routing
+\annotatedlist qml-QtLocation5-routing
+
+
+
+\section1 Example
+
+The above snippets are taken from the \l {Map Viewer (QML)}{Map Viewer (QML)} example.
+
+*/
+