QtPositioning: more documentation fixes

This patch fixes some typos, linking issues and improves wording
in some places.

Task-number: QTBUG-89856
Change-Id: Ia77290aa94a1b786f633be75b907b9a6afb71698
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Alex Blasche <alexander.blasche@qt.io>

10 files changed, 75 insertions, 65 deletions

diff --git a/src/positioning/doc/src/cpp-position.qdoc b/src/positioning/doc/src/cpp-position.qdoc
index 0205ad08..a380f105 100644
--- a/src/positioning/doc/src/cpp-position.qdoc
+++ b/src/positioning/doc/src/cpp-position.qdoc
@@ -35,9 +35,11 @@ GPS or an NMEA data source.
 
 \section1 Positioning
 
-The Positioning component of the Qt Location API is about the geographical position, size
-and address of some place. Positioning contains a QGeoCoordinate class, containing latitude, longitude and altitude in meters. QGeoLocation contains a QGeoCoordinate plus address
-and size information (a bounding box) so that positions can be more than mathematical points.
+The Positioning component of the Qt Location API is about the geographical
+position, size, and address of some place. Positioning contains a
+\l QGeoCoordinate class, containing latitude, longitude and altitude in meters.
+\l QGeoLocation contains a \l QGeoCoordinate plus address and size information
+(a bounding box) so that positions can be more than mathematical points.
 Movement into or out of the defined bounding box areas can be monitored. The API
 also allows the developer to control the source of the positional information
 as well.
@@ -66,9 +68,9 @@ latitude-longitude coordinate with a date/time value, with the option of
 providing the other attributes listed above.
 
 
-Location data sources are created by subclassing QGeoPositionInfoSource and
-providing QGeoPositionInfo objects through the
-QGeoPositionInfoSource::positionUpdated() signal. Clients that require
+Location data sources are created by subclassing \l QGeoPositionInfoSource and
+providing \l QGeoPositionInfo objects through the
+\l {QGeoPositionInfoSource::positionUpdated()} signal. Clients that require
 location data can connect to the
 \l{QGeoPositionInfoSource::positionUpdated()}{positionUpdated()} signal and
 call \l{QGeoPositionInfoSource::startUpdates()}{startUpdates()} or
@@ -77,24 +79,25 @@ distribution of location data. The location data distribution can be stopped by
 calling the \l {QGeoPositionInfoSource::stopUpdates()}{stopUpdates()} function.
 
 A default position source may be available on some platforms. Call
-QGeoPositionInfoSource::createDefaultSource() to create an instance of the default
-position source; the method returns 0 if no default source is available for
-the platform.
+\l {QGeoPositionInfoSource::createDefaultSource()} to create an instance of the
+default position source. The method returns \c nullptr if no default source is
+available for the platform.
 
 If a problem occurs with access to the information source then an
 \l {QGeoPositionInfoSource::errorOccurred()}{errorOccurred()} signal is emitted.
 
-The QGeoAreaMonitorSource class enables client applications to be notified when
-the receiving device has moved in or out of a particular area, as specified
-by a coordinate and radius. If the platform provides built-in support for
-area monitoring, QGeoAreaMonitorSource::createDefaultMonitor() returns an instance of
-the default area monitor.
+The \l QGeoAreaMonitorSource class enables client applications to be notified
+when the receiving device has moved into or out of a particular area, as
+specified by a coordinate and radius. If the platform provides built-in support
+for area monitoring, the \l {QGeoAreaMonitorSource::createDefaultSource()}
+method returns an instance of the default area monitor.
 
 Satellite information can also be distributed through the
-QGeoSatelliteInfoSource class. Call QGeoSatelliteInfoSource::createDefaultSource() to
-create an instance of the default satellite data source for the platform,
-if one is available. Alternatively, clients can subclass it to provide a
-custom satellite data source.
+\l QGeoSatelliteInfoSource class. Call
+\l {QGeoSatelliteInfoSource::createDefaultSource()} to create an instance of the
+default satellite data source for the platform if one is available.
+Alternatively, clients can subclass it to provide a custom satellite data
+source.
 
 
 
@@ -106,7 +109,7 @@ then call either \l{QGeoPositionInfoSource::startUpdates()}{startUpdates()}
 or \l{QGeoPositionInfoSource::requestUpdate()}{requestUpdate()} to begin.
 
 Here is an example of a client that receives data from the default location
-data source, as returned by QGeoPositionInfoSource::createDefaultSource():
+data source, as returned by \l {QGeoPositionInfoSource::createDefaultSource()}:
 
 \code
 class MyClass : public QObject
@@ -135,20 +138,20 @@ private slots:
 
 \section2 Controlling Aspects of Data Sources
 
-The QGeoPositionInfoSource::setUpdateInterval() method can be used to
+The \l {QGeoPositionInfoSource::setUpdateInterval()} method can be used to
 control the rate at which position updates are received. For example, if
 the client application only requires updates once every 30 seconds, it can
-call \c setUpdateInterval(30000). (If no update interval is set, or
-\l {QGeoPositionInfoSource::}{setUpdateInterval()} is called with a value of 0, the source uses a default
-interval or some other internal logic to determine when updates should be
-provided.)
+call \c setUpdateInterval(30000). If no update interval is set, or
+\l {QGeoPositionInfoSource::}{setUpdateInterval()} is called with a value of 0,
+the source uses a default interval or some other internal logic to determine
+when updates should be provided.
 
-QGeoPositionInfoSource::setPreferredPositioningMethods() enables client
+\l {QGeoPositionInfoSource::setPreferredPositioningMethods()} enables client
 applications to request that a certain type of positioning method be used.
 For example, if the application prefers to use only satellite positioning,
 which offers fairly precise outdoor positioning but can be a heavy user of
 power resources, it can call this method with the
-QGeoPositionInfoSource::SatellitePositioningMethods value. However, this
+\l {QGeoPositionInfoSource::SatellitePositioningMethods} value. However, this
 method should only be used in specialized client applications; in most
 cases, the default positioning methods should not be changed, as a source
 may internally use a variety of positioning methods that can be useful to
@@ -158,7 +161,7 @@ the application.
 
 \l {http://en.wikipedia.org/wiki/NMEA_0183}{NMEA} is a common text-based
 protocol for specifying navigational data. For convenience, the
-QNmeaPositionInfoSource is provided to enable client applications to read
+\l QNmeaPositionInfoSource is provided to enable client applications to read
 and distribute NMEA data in either real-time mode (for example, when
 streaming from a GPS device) or simulation mode (for example, when reading
 from a NMEA log file). In simulation mode, the source will emit updates
@@ -166,13 +169,13 @@ according to the time stamp of each NMEA sentence to produce a "replay"
 of the recorded data.
 
 Generally, the capabilities provided by the default position source as
-returned by QGeoPositionInfoSource::createDefaultSource(), along with the
-QNmeaPositionInfoSource class, are sufficient for retrieving location
+returned by \l {QGeoPositionInfoSource::createDefaultSource()}, along with the
+\l QNmeaPositionInfoSource class, are sufficient for retrieving location
 data. However, in some cases developers may wish to write their own custom
 location data source.
 
-The \l {Log File Position Source (C++)} example demonstrates how to subclass QGeoPositionInfoSource
-to create a custom positioning source.
+The \l {Log File Position Source (C++)} example demonstrates how to subclass
+\l QGeoPositionInfoSource to create a custom positioning source.
 
 
 \section1 Examples
diff --git a/src/positioning/doc/src/qml-position.qdoc b/src/positioning/doc/src/qml-position.qdoc
index 3f112b79..27e55583 100644
--- a/src/positioning/doc/src/qml-position.qdoc
+++ b/src/positioning/doc/src/qml-position.qdoc
@@ -71,7 +71,7 @@ The \l {coordinate} is a basic unit of geographical information. The
 
 The three dimensional position of an object such as a mobile device can be specified by giving
 the latitude, longitude and altitude.  That is the values held in the
-l\ {coordinate} type.  Additionally for computation of future
+\l {coordinate} type.  Additionally for computation of future
 positions we would like to know if the object is moving, what \l [QML] {Position::}{speed} it is
 doing and what is the \l {Position::timestamp}{timestamp} of the last position data.  Position
 therefore includes values for the \l {Position::coordinate}{coordinate},
@@ -85,10 +85,10 @@ the \l {Position::latitudeValid}{latitudeValid}, \l {Position::longitudeValid}{l
 
 \section2 PositionSource Type
 
-We have a Position type, a \l {coordinate} type but where does the data come from?
-Also it is a good idea to be able to indicate alternative sources.
-Perhaps instead of directly picking up GPS satellites it might be desirable to do
-some testing using a datafile.
+We have a \l Position type, a \l {coordinate} type but where does the data come
+from? Also it is a good idea to be able to indicate alternative sources.
+Perhaps instead of directly picking up GPS satellites it might be desirable to
+do some testing using a datafile.
 
 The \l PositionSource type provides the developer with control, within the
 limits allowed by the platform, of the source of the geographical data.
diff --git a/src/positioning/qgeoareamonitorinfo.cpp b/src/positioning/qgeoareamonitorinfo.cpp
index fd0f3283..1ca5b34c 100644
--- a/src/positioning/qgeoareamonitorinfo.cpp
+++ b/src/positioning/qgeoareamonitorinfo.cpp
@@ -194,7 +194,7 @@ bool QGeoAreaMonitorInfo::operator!=(const QGeoAreaMonitorInfo &other) const
 }
 
 /*!
-    Returns the name of the QGeoAreaMonitorInfo object. The name should be used to
+    Returns the name of the QGeoAreaMonitorInfo object. The name should be used
     for user-visibility purposes.
  */
 QString QGeoAreaMonitorInfo::name() const
@@ -301,10 +301,11 @@ bool QGeoAreaMonitorInfo::isPersistent() const
 }
 
 /*!
-    Sets the QGeoAreaMonitorInfo objects persistence to \a isPersistent.
+    Sets the QGeoAreaMonitorInfo object's persistence to \a isPersistent.
 
-    Note that setting this flag does not imply that QGeoAreaMonitorInfoSource supports persistent
-    monitoring. \l QGeoAreaMonitorSource::supportedAreaMonitorFeatures() can be used to
+    Note that setting this flag does not imply that \l QGeoAreaMonitorSource
+    supports persistent monitoring.
+    \l QGeoAreaMonitorSource::supportedAreaMonitorFeatures() can be used to
     check for this feature's availability.
 
     \sa isPersistent()
@@ -317,7 +318,8 @@ void QGeoAreaMonitorInfo::setPersistent(bool isPersistent)
 
 
 /*!
-    Returns the set of platform specific paraemters used by this QGeoAreaMonitorInfo.
+    Returns the set of platform specific parameters used by this
+    QGeoAreaMonitorInfo.
 
     \sa setNotificationParameters()
  */
diff --git a/src/positioning/qgeoareamonitorsource.cpp b/src/positioning/qgeoareamonitorsource.cpp
index 412919a0..8a09e918 100644
--- a/src/positioning/qgeoareamonitorsource.cpp
+++ b/src/positioning/qgeoareamonitorsource.cpp
@@ -124,7 +124,7 @@ public:
 */
 
 /*!
-    Creates a monitor with the given \a parent.
+    Creates a monitor source with the given \a parent.
 */
 QGeoAreaMonitorSource::QGeoAreaMonitorSource(QObject *parent)
         : QObject(*new QGeoAreaMonitorSourcePrivate, parent)
@@ -134,14 +134,14 @@ QGeoAreaMonitorSource::QGeoAreaMonitorSource(QObject *parent)
 }
 
 /*!
-    Destroys the monitor.
+    Destroys the monitor source.
 */
 QGeoAreaMonitorSource::~QGeoAreaMonitorSource()
 {
 }
 
 /*!
-    Creates and returns a monitor with the given \a parent that
+    Creates and returns a monitor source with the given \a parent that
     monitors areas using resources on the underlying system.
 
     Returns \c nullptr if the system has no support for position monitoring.
@@ -162,12 +162,11 @@ QGeoAreaMonitorSource *QGeoAreaMonitorSource::createDefaultSource(QObject *paren
             return s;
         }
     }
-
     return nullptr;
 }
 
 /*!
-    Creates and returns a monitor with the given \a parent,
+    Creates and returns a monitor source with the given \a parent,
     by loading the plugin named \a sourceName.
 
     Returns \c nullptr if the plugin cannot be found.
@@ -265,11 +264,11 @@ void QGeoAreaMonitorSource::setPositionInfoSource(QGeoPositionInfoSource *newSou
     \fn virtual bool QGeoAreaMonitorSource::startMonitoring(const QGeoAreaMonitorInfo &monitor)
 
     Returns \c true if the monitoring of \a monitor could be successfully started; otherwise
-    returns false. A reason for not being able to start monitoring could be the unavailability
+    returns \c false. A reason for not being able to start monitoring could be the unavailability
     of an appropriate default position info source while no alternative QGeoPositionInfoSource
     has been set via \l setPositionInfoSource().
 
-    If \a monitor is already active the existing monitor object will be replaced by the new \a monitor reference.
+    If \a monitor is already active, the existing monitor object will be replaced by the new \a monitor reference.
     The identification of QGeoAreaMonitorInfo instances happens via \l QGeoAreaMonitorInfo::identifier().
     Therefore this function can also be used to update active monitors.
 
@@ -291,8 +290,9 @@ void QGeoAreaMonitorSource::setPositionInfoSource(QGeoPositionInfoSource *newSou
 
     Enables single shot area monitoring. Area monitoring for \a monitor will be performed
     until this QGeoAreaMonitorSource instance emits \a signal for the first time. Once
-    the signal was emitted, \a monitor is automatically removed from the list of \l activeMonitors().
-    If \a monitor is invalid or has an expiry date that has been passed this function returns false.
+    the signal was emitted, \a monitor is automatically removed from the list of
+    \l activeMonitors(). If \a monitor is invalid or has an expiry date that has
+    been passed, this function returns \c false.
 
     \code
         QGeoAreaMonitor singleShotMonitor;
@@ -336,9 +336,10 @@ void QGeoAreaMonitorSource::setPositionInfoSource(QGeoPositionInfoSource *newSou
 
     Returns the list of all active monitors known to the QGeoAreaMonitorSource object.
 
-    An active monitor was started via startMonitoring() the source object will emit
-    the required signals such as areaEntered() or areaExited(). Multiple \l QGeoAreaMonitorSource
-    instances within the same application share the same active monitor objects.
+    An active monitor was started via startMonitoring(). For every active
+    monitor the source object will emit the required signals, such as
+    areaEntered() or areaExited(). Multiple \l QGeoAreaMonitorSource instances
+    within the same application share the same active monitor objects.
 
     Unless an active QGeoAreaMonitorInfo \l {QGeoAreaMonitorInfo::isPersistent()}{isPersistent()} an active QGeoAreaMonitorInfo
     will be stopped once the current application terminates.
@@ -350,9 +351,10 @@ void QGeoAreaMonitorSource::setPositionInfoSource(QGeoPositionInfoSource *newSou
     Returns the list of all active monitors known to the QGeoAreaMonitorSource object whose
     center lies within \a lookupArea. If \a lookupArea is empty the returned list will be empty.
 
-    An active monitor was started via startMonitoring() and the source object will emit
-    the required signals such as areaEntered() or areaExited(). Multiple QGeoAreaMonitorSource
-    instances within the same application share the same monitor objects.
+    An active monitor was started via startMonitoring(). For every active
+    monitor the source object will emit the required signals, such as
+    areaEntered() or areaExited(). Multiple \l QGeoAreaMonitorSource instances
+    within the same application share the same active monitor objects.
 
     Unless an active QGeoAreaMonitorInfo \l {QGeoAreaMonitorInfo::isPersistent()}{isPersistent()} an active QGeoAreaMonitorInfo
     will be stopped once the current application terminates.
diff --git a/src/positioning/qgeolocation.cpp b/src/positioning/qgeolocation.cpp
index 086529da..41022837 100644
--- a/src/positioning/qgeolocation.cpp
+++ b/src/positioning/qgeolocation.cpp
@@ -88,7 +88,7 @@ bool QGeoLocationPrivate::isEmpty() const
     \brief The QGeoLocation class represents basic information about a location.
 
     A QGeoLocation consists of a coordinate and corresponding address, along with an optional
-    bounding box which is the recommended region to be displayed when viewing the location.
+    bounding shape, which is the recommended region to be displayed when viewing the location.
 */
 
 /*!
@@ -226,7 +226,9 @@ void QGeoLocation::setExtendedAttributes(const QVariantMap &data)
 }
 
 /*!
-    Returns true if all fields of the location are 0; otherwise returns false.
+    Returns \c true if the location coordinate is \l {QGeoCoordinate::isValid}
+    {invalid}, and all the other location fields are empty. Otherwise returns
+    \c false.
 */
 bool QGeoLocation::isEmpty() const
 {
diff --git a/src/positioning/qgeopath.cpp b/src/positioning/qgeopath.cpp
index c4028642..ad2c4ffe 100644
--- a/src/positioning/qgeopath.cpp
+++ b/src/positioning/qgeopath.cpp
@@ -58,7 +58,7 @@ QT_BEGIN_NAMESPACE
 
     \brief The QGeoPath class defines a geographic path.
 
-    The path is defined by an ordered list of QGeoCoordinates.
+    The path is defined by an ordered list of \l QGeoCoordinate objects.
 
     Each two adjacent elements in the path are intended to be connected
     together by the shortest line segment of constant bearing passing
diff --git a/src/positioning/qgeopolygon.cpp b/src/positioning/qgeopolygon.cpp
index 7acffbfa..a1197069 100644
--- a/src/positioning/qgeopolygon.cpp
+++ b/src/positioning/qgeopolygon.cpp
@@ -61,7 +61,8 @@ QT_BEGIN_NAMESPACE
 
     \brief The QGeoPolygon class defines a geographic polygon.
 
-    The polygon is defined by an ordered list of QGeoCoordinates representing its perimeter.
+    The polygon is defined by an ordered list of \l QGeoCoordinate objects
+    representing its perimeter.
 
     Each two adjacent elements in this list are intended to be connected
     together by the shortest line segment of constant bearing passing
@@ -413,7 +414,7 @@ void QGeoPolygon::addHole(const QList<QGeoCoordinate> &holePath)
 }
 
 /*!
-    Returns a QVariant containing a QVariant containing a QList<QGeoCoordinate>
+    Returns a QVariant containing a QList<QGeoCoordinate>
     which represents the hole at \a index.
 
     \since 5.12
@@ -439,7 +440,7 @@ const QList<QGeoCoordinate> QGeoPolygon::holePath(int index) const
 }
 
 /*!
-    Removes element at position \a index from the holes QList.
+    Removes element at position \a index from the list of holes.
 
     \since 5.12
 */
diff --git a/src/positioning/qgeosatelliteinfosource.cpp b/src/positioning/qgeosatelliteinfosource.cpp
index 89607438..9e80a1d2 100644
--- a/src/positioning/qgeosatelliteinfosource.cpp
+++ b/src/positioning/qgeosatelliteinfosource.cpp
@@ -146,7 +146,7 @@ QString QGeoSatelliteInfoSource::sourceName() const
 
     The default value for this property is 0.
 
-    Note: Subclass implementations must call the base implementation of
+    \note Subclass implementations must call the base implementation of
     setUpdateInterval() so that updateInterval() returns the correct value.
 */
 void QGeoSatelliteInfoSource::setUpdateInterval(int msec)
diff --git a/src/positioningquick/qdeclarativegeolocation.cpp b/src/positioningquick/qdeclarativegeolocation.cpp
index 200b5ed4..97f6829c 100644
--- a/src/positioningquick/qdeclarativegeolocation.cpp
+++ b/src/positioningquick/qdeclarativegeolocation.cpp
@@ -194,7 +194,7 @@ QGeoCoordinate QDeclarativeGeoLocation::coordinate() const
     \l georectangle for the shape.
 
     If you need to convert the returned shape to a specific type, use the
-    \c {ShapeType type} property of \l geoshape together with convenience
+    \c type property of \l geoshape together with convenience
     methods from \l [QML]{QtPositioning} like
     \l {QtPositioning::shapeToRectangle}{QtPositioning.shapeToRectangle()}.
 */
diff --git a/src/positioningquick/qdeclarativepositionsource.cpp b/src/positioningquick/qdeclarativepositionsource.cpp
index 696f461b..07108dce 100644
--- a/src/positioningquick/qdeclarativepositionsource.cpp
+++ b/src/positioningquick/qdeclarativepositionsource.cpp
@@ -599,7 +599,7 @@ QGeoPositionInfoSource *QDeclarativePositionSource::positionSource() const
 
 /*!
     \qmlproperty list<PluginParameter> PositionSource::parameters
-    \default
+    \qmldefault
 
     This property holds the list of plugin parameters.