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>

1 files changed, 29 insertions, 0 deletions

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()
 {