Many documentation improvements

Courtesy of the Caped Crusader:

QDeclarativeGeoAddress
    - fixed "brief" description of Address element
    - removed reference to "the plugin" from text property description

QDeclarativeBoundingBox
    - added description of BoundingBox element
    - added example of usage

QDeclarativeBoundingCircle
    - added description of BoundingCircle element
    - added example of usage
    - added note about change signal semantics from center coordinate

QDeclarativeCoordinate
    -> NOT DONE: adding "general terminology" (azimuth etc etc)
    - added important note about change signal notification semantics (incl. Position-exception)
    - added documentation about what constitutes "validity" of lat/long
    - added units for the azimuth (degrees, not radians)
        - QGeoCoordinatePrivate::atDistanceAndAzimuth() does: double azimuthRad = qgeocoordinate_degToRad(azimuth);

QDeclarativeGeoLocation
    - changed "coordinate" property documentation

QDeclarativePosition
    - updated description to underline it's temporal nature
    - updated property descriptions to underline read-only nature of Position

QDeclarativePositionSource
    -> NOT DONE: updating the "active" property documentation to clarify "is/should-be" semantics.
    - updated description to avoid implying that you must specify an updateInterval.
    - updated description to clarify onPositionChanged is a signal-handler.
    - added description of NMEA data
    - added note that the "position" property is read-only.
    - clarified scope and description of positioning method enum values
    - clarified scope of error enum values
    - added documentation for onPositionChanged signal handler.
    - added documentation for update() regarding timeout value and activation.

Places.qdoc
    - shortened a long line, lengthened a short line.
    - clarified save/remove documentation

Change-Id: I6793906b7f5ebf7ccc5432d85822506466341057
Reviewed-by: Aaron McCarthy <aaron.mccarthy@nokia.com>

7 files changed, 134 insertions, 36 deletions

diff --git a/src/imports/location/qdeclarativecoordinate.cpp b/src/imports/location/qdeclarativecoordinate.cpp
index 5fb4f608..e860e6ea 100644
--- a/src/imports/location/qdeclarativecoordinate.cpp
+++ b/src/imports/location/qdeclarativecoordinate.cpp
@@ -95,6 +95,12 @@ QT_BEGIN_NAMESPACE
     As an example, the value of \c{coord1.distanceTo(coord2)} would now be
     approximately 34790 (34.8 km).
 
+    \b{NOTE:} if another element has a Coordinate property, a change notification
+    signal for that property will only be emitted if that property is assigned
+    a new Coordinate, and \b{not} if the position data of the existing Coordinate
+    assigned to the property changes.  The only exception to this rule is that
+    the \l{QDeclarativePosition}{Position} element does emit change signals if
+    its coordinate property's values change.
 */
 
 QDeclarativeCoordinate::QDeclarativeCoordinate(QObject* parent)
@@ -241,6 +247,10 @@ double QDeclarativeCoordinate::latitude() const
     This property holds the current validity of the coordinate. Coordinates
     are considered valid if they have been set with a valid latitude and
     longitude (altitude is not required).
+
+    The latitude must be between -90 to 90 inclusive to be considered valid,
+    and the longitude must be between -180 to 180 inclusive to be considered
+    valid.
 */
 
 bool QDeclarativeCoordinate::isValid() const
@@ -284,7 +294,7 @@ qreal QDeclarativeCoordinate::azimuthTo(QObject *coordinate)
     \qmlmethod Coordinate::atDistanceAndAzimuth(qreal, qreal)
 
     Returns the coordinate that is reached by traveling distance metres
-    from the current coordinate at azimuth (or bearing) along a great-circle.
+    from the current coordinate at azimuth degrees along a great-circle.
 
     There is an assumption that the Earth is spherical for the purpose
     of this calculation.
diff --git a/src/imports/location/qdeclarativegeoaddress.cpp b/src/imports/location/qdeclarativegeoaddress.cpp
index c745b032..483bd4ee 100644
--- a/src/imports/location/qdeclarativegeoaddress.cpp
+++ b/src/imports/location/qdeclarativegeoaddress.cpp
@@ -49,11 +49,11 @@ QT_BEGIN_NAMESPACE
     \ingroup qml-QtLocation5-positioning
     \since QtLocation 5.0
 
-    \brief The Address element presents an address.
+    \brief The Address QML element represents a specific location as a street address.
 
-    The Address element presents an address of a location. This is used as a
-    unit of data for queries such as (Reverse) Geocoding or Places searches --
-    many of these operations either accept an Address or return one.
+    An Address is used as a unit of data for queries such as (Reverse) Geocoding
+    or Places searches -- many of these operations either accept an Address
+    or return one.
 
     Not all properties of an Address are necessarily available or relevant
     in all parts of the world and all locales. The \l district, \l state and
@@ -99,7 +99,7 @@ QGeoAddress QDeclarativeGeoAddress::address() const
 /*!
     \qmlproperty QGeoAddress QtLocation5::Address::address
 
-    This property is used to provide an interface between C++ and QML code.  First a pointer to a
+    This property is used to provide an interface between C++ and QML code.  First a pointer to an
     Address object must be obtained from C++, then use the \l {QObject::property()}{property()} and
     \l {QObject::setProperty()}{setProperty()} functions to get and set the \c address property.
 
@@ -132,9 +132,9 @@ void QDeclarativeGeoAddress::setAddress(const QGeoAddress& address)
     This property holds the address as a single formatted string.  If this property is not empty
     then it is the recommended string to use to display the address to the user.
 
-    The address text may contain a subset of all address properties and is provided by the
-    \l Plugin.  A common pattern is for the text to take the format of an address as found on an
-    envelope, but this is not always necessarily the case.
+    The address text may contain a subset of all address properties.  A common pattern is for the
+    text to take the format of an address as found on an envelope, but this is not always necessarily
+    the case.
 */
 QString QDeclarativeGeoAddress::text() const
 {
diff --git a/src/imports/location/qdeclarativegeoboundingbox.cpp b/src/imports/location/qdeclarativegeoboundingbox.cpp
index 750a8faf..1f7528e2 100644
--- a/src/imports/location/qdeclarativegeoboundingbox.cpp
+++ b/src/imports/location/qdeclarativegeoboundingbox.cpp
@@ -52,7 +52,43 @@ QT_BEGIN_NAMESPACE
 
     \brief The BoundingBox element represents a rectangular geographic area.
 
-    For behavioral details, please see \l QGeoBoundingBox.
+    A BoundingBox is described by a \l{QDeclarativeCoordinate}{Coordinate} which
+    represents the top-left of the BoundingBox and a second
+    \l{QDeclarativeCoordinate}{Coordinate} which represents the bottom-right of
+    BoundingBox.
+
+    A BoundingBox is considered invalid if the top-left or bottom-right
+    coordinates are invalid or if the top-left coordinate is South of the
+    bottom-right coordinate.
+
+    Bounding boxes can never cross the poles.
+
+    If the height or center of a bounding box is adjusted such that it would
+    cross one of the poles the height is modified such that the bounding box
+    touches but does not cross the pole and that the center coordinate is still
+    in the center of the bounding box.
+
+    \section2 Example Usage
+
+    The following code snippet shows the declaration of a BoundingBox element.
+
+    \code
+    BoundingBox {
+        topLeft: Coordinate {
+            latitude: 23.34
+            longitude: 44.4
+        }
+        bottomRight: Coordinate {
+            latitude: 22.25
+            longitude: 42.88
+        }
+    }
+    \endcode
+
+    This could then be used, for example, as a region to scan for landmarks,
+    or refining searches.
+
+    \sa QGeoBoundingBox.
 */
 
 QDeclarativeGeoBoundingBox::QDeclarativeGeoBoundingBox(QObject* parent)
diff --git a/src/imports/location/qdeclarativegeoboundingcircle.cpp b/src/imports/location/qdeclarativegeoboundingcircle.cpp
index 898fa6ee..2c56ac53 100644
--- a/src/imports/location/qdeclarativegeoboundingcircle.cpp
+++ b/src/imports/location/qdeclarativegeoboundingcircle.cpp
@@ -51,6 +51,32 @@ QT_BEGIN_NAMESPACE
     \since QtLocation 5.0
 
     \brief The BoundingCircle element represents a circular geographic area.
+
+    The circle is defined in terms of a \l{QDeclarativeCoordinate}{Coordinate}
+    which specifies the center of the circle and a qreal which specifies the
+    radius of the circle in meters.
+
+    The circle is considered invalid if the center coordinate is invalid
+    or if the radius is less than zero.
+
+    \section2 Example Usage
+
+    The following code snippet shows the declaration of a BoundingCircle element.
+
+    \code
+    BoundingCircle {
+        radius: 25.0
+        center: Coordinate {
+            latitude: 23.34
+            longitude: 44.4
+        }
+    }
+    \endcode
+
+    This could then be used, for example, as a region to scan for landmarks,
+    or refining searches.
+
+    \sa QGeoBoundingCircle
 */
 
 QDeclarativeGeoBoundingCircle::QDeclarativeGeoBoundingCircle(QObject *parent)
@@ -115,6 +141,9 @@ bool QDeclarativeGeoBoundingCircle::contains(QDeclarativeCoordinate *coordinate)
     \qmlproperty Coordinate BoundingCircle::center
 
     This property holds the coordinate of the center of the bounding circle.
+
+    Note: this property's changed() signal is currently emitted only if the
+    whole element changes, not if only the contents of the element change.
 */
 QDeclarativeCoordinate* QDeclarativeGeoBoundingCircle::center()
 {
diff --git a/src/imports/location/qdeclarativegeolocation.cpp b/src/imports/location/qdeclarativegeolocation.cpp
index 65acfe39..79776434 100644
--- a/src/imports/location/qdeclarativegeolocation.cpp
+++ b/src/imports/location/qdeclarativegeolocation.cpp
@@ -177,7 +177,7 @@ QDeclarativeGeoAddress *QDeclarativeGeoLocation::address()
 /*!
     \qmlproperty Coordinate QtLocation5::Location::coordinate
 
-    This property holds display coordinates of the location.
+    This property holds the exact geographical coordinate of the location.
 
     Note: this property's changed() signal is currently emitted only if the
     whole element changes, not if only the contents of the element change.
diff --git a/src/imports/location/qdeclarativeposition.cpp b/src/imports/location/qdeclarativeposition.cpp
index eccb3bd4..c0a1d4da 100644
--- a/src/imports/location/qdeclarativeposition.cpp
+++ b/src/imports/location/qdeclarativeposition.cpp
@@ -52,11 +52,14 @@ QT_BEGIN_NAMESPACE
     \ingroup qml-QtLocation5-positioning
     \since QtLocation 5.0
 
-    \brief The Position element holds various positional data, such as coordinate
-    (longitude, latitude, altitude) and speed.
+    \brief The Position element holds positional data at a particular point in time,
+    such as coordinate (longitude, latitude, altitude) and speed.
+
+    The Position element holds values related to geographic location such as
+    a \l coordinate (longitude, latitude, and altitude), the \l timestamp when
+    the Position was obtained, the \l speed at that time, and the accuracy of
+    the data.
 
-    The Position element holds various positional data, such as \l coordinate,
-    (longitude, latitude, and altitude) and \l speed, as well as \l timestamp.
     Primarily, it is used in the \l{PositionSource::position}{position} property
     of a \l{PositionSource}, as the basic unit of data available from the system
     location data source.
@@ -96,8 +99,10 @@ QDeclarativePosition::~QDeclarativePosition()
     This property holds the latitude, longitude, and altitude
     value of the Position.
 
+    It is a read-only property.
+
     Note: due to its inherent changing nature, the coordinateChanged()
-    - signal is emitted also when the values of the coordinate changes,
+    signal is emitted also when the values of the coordinate change,
     which enables easier data binding to Coordinate element instead of
     directly connecting to e.g. its latitude and longitude.
 
@@ -213,7 +218,8 @@ bool QDeclarativePosition::isAltitudeValid() const
     \qmlproperty double Position::speed
 
     This property holds the value of speed (groundspeed, meters / second).
-    Currently a read-only property.
+
+    It is a read-only property.
 
     \sa speedValid, coordinate
 */
@@ -323,6 +329,7 @@ bool QDeclarativePosition::isVerticalAccuracyValid() const
     This property holds the timestamp when this position
     was received. If the property has not been set, it is invalid.
 
+    It is a read-only property.
 */
 
 void QDeclarativePosition::setTimestamp(const QDateTime& timestamp)
diff --git a/src/imports/location/qdeclarativepositionsource.cpp b/src/imports/location/qdeclarativepositionsource.cpp
index 66e4392e..155430cf 100644
--- a/src/imports/location/qdeclarativepositionsource.cpp
+++ b/src/imports/location/qdeclarativepositionsource.cpp
@@ -74,15 +74,15 @@ QT_BEGIN_NAMESPACE
     chosen instead.
 
     The \l updateInterval property can then be used to indicate how often your
-    application wishes to receive position updates. Once set, the \l{start}(),
+    application wishes to receive position updates. The \l{start}(),
     \l{stop}() and \l{update}() methods can be used to control the operation
     of the PositionSource, as well as the \l{active} property, which when set
     is equivalent to calling \l{start}() or \l{stop}().
 
     When the PositionSource is active, position updates can be retrieved
     either by simply using the \l{position} property in a binding (as the
-    value of another item's property), or by providing a handler for the
-    \l{onPositionChanged} signal.
+    value of another item's property), or by providing an implementation of
+    the \l{onPositionChanged} signal-handler.
 
     \section2 Example Usage
 
@@ -217,11 +217,12 @@ void QDeclarativePositionSource::setUpdateInterval(int updateInterval)
 /*!
     \qmlproperty url PositionSource::nmeaSource
 
-    This property holds the source for NMEA data (file). One purpose of this
-    property is to be of development convenience.
+    This property holds the source for NMEA (National Marine Electronics Association)
+    position-specification data (file). One purpose of this property is to be of
+    development convenience.
 
     Setting this property will override any other position source. Currently only
-    files local to the .qml -file are supported. Nmea source is created in simulation mode,
+    files local to the .qml -file are supported. The NMEA source is created in simulation mode,
     meaning that the data and time information in the NMEA source data is used to provide
     positional updates at the rate at which the data was originally recorded.
 
@@ -261,10 +262,10 @@ void QDeclarativePositionSource::setPreferredPositioningMethods(QGeoPositionInfo
     current source.
 
     \list
-    \li NoPositioningMethod - No positioning methods supported (no source).
-    \li SatellitePositioningMethod - Satellite-based positioning methods such as GPS is supported.
-    \li NonSatellitePositioningMethod - Non satellite methods are supported.
-    \li AllPositioningMethods - Combination of methods are supported.
+    \li PositionSource.NoPositioningMethod - No positioning methods supported (no source).
+    \li PositionSource.SatellitePositioningMethod - Satellite-based positioning methods such as GPS are supported.
+    \li PositionSource.NonSatellitePositioningMethod - Non-satellite-based methods are supported.
+    \li PositionSource.AllPositioningMethods - Both satellite-based and non-satellite positioning methods are supported.
     \endlist
 
 */
@@ -287,13 +288,13 @@ QDeclarativePositionSource::PositioningMethods QDeclarativePositionSource::suppo
 /*!
     \qmlproperty enumeration PositionSource::preferredPositioningMethods
 
-    This property holds the supported positioning methods of the
+    This property holds the preferred positioning methods of the
     current source.
 
     \list
-    \li SatellitePositioningMethod - Satellite-based positioning methods such as GPS is supported.
-    \li NonSatellitePositioningMethod - Non satellite methods are supported.
-    \li AllPositioningMethods - Combination of methods are supported.
+    \li PositionSource.SatellitePositioningMethod - Satellite-based positioning methods such as GPS should be preferred.
+    \li PositionSource.NonSatellitePositioningMethod - Non-satellite-based methods should be preferred.
+    \li PositionSource.AllPositioningMethods - Any positioning methods are acceptable.
     \endlist
 
 */
@@ -342,6 +343,10 @@ void QDeclarativePositionSource::start()
     A convenience method to request single update from the location source.
     If there is no source available, this method has no effect.
 
+    If the position source is not active, it will be activated for as
+    long as it takes to receive an update, or until the request times
+    out.  The request timeout period is source-specific.
+
     \sa start, stop, active
 */
 
@@ -389,7 +394,18 @@ void QDeclarativePositionSource::stop()
     position::latitude, position::longitude, and position::timestamp
     members of the \l position have been updated.
 
-    \sa updateInterval
+    \sa updateInterval, onPositionChanged
+
+*/
+
+/*!
+    \qmlslot PositionSource::onPositionChanged()
+
+    An implementation for this signal handler may be provided in
+    order to perform custom behavior when a position update has
+    been received.
+
+    \sa updateInterval, positionChanged
 
 */
 
@@ -424,6 +440,7 @@ bool QDeclarativePositionSource::isActive() const
     \qmlproperty Position PositionSource::position
 
     This property holds the last known positional data.
+    It is a read-only property.
 
     The Position element has different positional member variables,
     whose validity can be checked with appropriate validity functions
@@ -434,7 +451,6 @@ bool QDeclarativePositionSource::isActive() const
     be assumed to be valid.
 
     \sa start, stop, update
-
 */
 
 QDeclarativePosition* QDeclarativePositionSource::position()
@@ -478,12 +494,12 @@ QDeclarativePositionSource::SourceError QDeclarativePositionSource::sourceError(
     This property holds the error which last occured with the PositionSource.
 
     \list
-    \li AccessError - The connection setup to the remote positioning backend failed because the
+    \li PositionSource.AccessError - The connection setup to the remote positioning backend failed because the
         application lacked the required privileges.
-    \li ClosedError - The remote positioning backend closed the connection, which happens e.g. in case
+    \li PositionSource.ClosedError - The remote positioning backend closed the connection, which happens e.g. in case
         the user is switching location services to off. This object becomes invalid and should be deleted.
         A new source can be declared later on to check whether the positioning backend is up again.
-    \li UnknownSourceError - An unidentified error occurred.
+    \li PositionSource.UnknownSourceError - An unidentified error occurred.
     \endlist
 
 */