From c59ffd95ad36b8307d1fa6ab97973781f7f23a69 Mon Sep 17 00:00:00 2001 From: Volker Hilsheimer Date: Fri, 25 Nov 2022 17:13:21 +0100 Subject: Documentation fixes Correct spelling of and links to QML value types and to properties of value types. Remove some documentation and snippets that are mostly outdated, and links to specific plugin providers. Silence some warnings. Task-number: QTBUG-96795 Change-Id: Ifba3ae8144e0d949f1c72a4ea230e7f84fa28bd4 Reviewed-by: Alex Blasche --- examples/location/places/doc/src/places.qdoc | 6 +- .../location/places_list/doc/src/places_list.qdoc | 5 +- .../declarativemaps/qdeclarativegeoroutemodel.cpp | 7 +- .../qdeclarativegeoserviceprovider.cpp | 26 +---- .../declarativeplaces/qdeclarativecategory.cpp | 6 +- .../qdeclarativecontactdetails.cpp | 7 +- .../declarativeplaces/qdeclarativeplace.cpp | 7 +- .../qdeclarativeplacecontentmodel.cpp | 37 +++++-- src/location/doc/qtlocation.qdocconf | 9 +- src/location/doc/src/cpp-qml.qdoc | 115 --------------------- src/location/doc/src/maps.qdoc | 2 +- src/location/doc/src/places.qdoc | 3 - src/location/doc/src/plugins/esri.qdoc | 1 + src/location/doc/src/plugins/mapboxgl.qdoc | 1 + src/location/doc/src/plugins/nokia.qdoc | 1 + src/location/doc/src/qt6-changes.qdoc | 6 +- src/location/doc/src/qtlocation-examples.qdoc | 3 +- src/location/doc/src/qtlocation-qml.qdoc | 4 +- src/location/maps/qgeocameracapabilities.cpp | 16 +-- src/location/maps/qgeoroute.cpp | 7 +- src/location/maps/qgeoserviceprovider.cpp | 13 +-- src/location/maps/qgeoserviceproviderfactory.cpp | 2 +- src/location/places/qplaceattribute.cpp | 7 +- src/location/places/qplacecontactdetail.cpp | 9 +- src/location/places/qplacecontent.cpp | 27 ++--- src/location/places/qplaceratings.cpp | 11 +- src/location/places/qplacesupplier.cpp | 4 +- src/location/places/qplaceuser.cpp | 4 +- .../quickmapitems/qdeclarativegeomapitemview.cpp | 2 +- .../quickmapitems/qdeclarativeroutemapitem.cpp | 2 +- 30 files changed, 100 insertions(+), 250 deletions(-) delete mode 100644 src/location/doc/src/cpp-qml.qdoc diff --git a/examples/location/places/doc/src/places.qdoc b/examples/location/places/doc/src/places.qdoc index b3c18313..d442f2b1 100644 --- a/examples/location/places/doc/src/places.qdoc +++ b/examples/location/places/doc/src/places.qdoc @@ -51,9 +51,9 @@ desired category. The place search query will be for places that are near the current location shown on the map. - For some plugins like \l {Qt Location HERE Plugin} the search box provides search term - suggestions when three or more characters are entered. Selecting one of the suggestions will - cause a place search to be performed with the selected search text. + For some plugins, the search box provides search term suggestions when three or more characters + are entered. Selecting one of the suggestions will cause a place search to be performed with + the selected search text. Clicking on a search result will display details about the place. If a places has rich content (editorials, reviews and images), these can be accessed by the buttons on the details page. diff --git a/examples/location/places_list/doc/src/places_list.qdoc b/examples/location/places_list/doc/src/places_list.qdoc index bc19d561..b66d8e44 100644 --- a/examples/location/places_list/doc/src/places_list.qdoc +++ b/examples/location/places_list/doc/src/places_list.qdoc @@ -50,9 +50,8 @@ from where places are sourced from. Depending on the type of the plugin, some mandatory parameters may be need to be filled in. The most likely type of PluginParameter are some form of service access token which are documented - in the service plugin. As an example see the \l - {Mandatory Parameters} {HERE Plugin} documentation. In this snippet the \c osm - plugin is used which does not require any further parameter: + in the service plugin. In this snippet the \c osm plugin is used which does + not require any further parameter: \snippet places_list/places_list.qml Initialize Plugin diff --git a/src/location/declarativemaps/qdeclarativegeoroutemodel.cpp b/src/location/declarativemaps/qdeclarativegeoroutemodel.cpp index 5ad1df4e..6a622a72 100644 --- a/src/location/declarativemaps/qdeclarativegeoroutemodel.cpp +++ b/src/location/declarativemaps/qdeclarativegeoroutemodel.cpp @@ -106,8 +106,8 @@ static QList waypointCoordinates(const QList QGeoRoute::segments() const */ /*! - \property QGeoRoute::traveltime + \property QGeoRoute::travelTime \brief the estimated amount of time it will take to traverse this route, in seconds */ @@ -391,7 +391,6 @@ QList QGeoRoute::path() const \property QGeoRoute::routeLegs \brief the route \a legs for a multi-waypoint route - \sa QGeoRouteLeg \since 5.12 */ void QGeoRoute::setRouteLegs(const QList &legs) diff --git a/src/location/maps/qgeoserviceprovider.cpp b/src/location/maps/qgeoserviceprovider.cpp index 17ee11ce..989bcf9d 100644 --- a/src/location/maps/qgeoserviceprovider.cpp +++ b/src/location/maps/qgeoserviceprovider.cpp @@ -96,20 +96,9 @@ Q_GLOBAL_STATIC_WITH_ARGS(QFactoryLoader, loader, Subclasses of QGeoServiceProvider guarantee that the different services that they provide are interoperable. - At this point there are two GeoServices plugins packaged with Qt. They are - accessible using their provider names: - - \list - \li "mapbox" -> \l {Qt Location Mapbox Plugin}{Mapbox service} - \li "here" -> \l {Qt Location HERE Plugin}{HERE Services} - \li "osm" -> \l {Qt Location Open Street Map Plugin}{OpenStreetMap Services} - \li "esri" -> \l {Qt Location Esri Plugin}{ESRI Services} - \endlist - Each service provider must follow a naming convention for their service specific parameter names/keys. They use the provider name as prefix for all their - parameter names. For example, the \l {Qt Location HERE Plugin}{HERE} service provider - requires the \c here.app_id parameter. When a provider is loaded only those parameters are + parameter names. When a provider is loaded only those parameters are passed on whose parameter names start with the provider name. This avoids the sharing sensitive parameters such as confidential \c token or \c app_id parameters with other plugins. diff --git a/src/location/maps/qgeoserviceproviderfactory.cpp b/src/location/maps/qgeoserviceproviderfactory.cpp index d58773bd..984215aa 100644 --- a/src/location/maps/qgeoserviceproviderfactory.cpp +++ b/src/location/maps/qgeoserviceproviderfactory.cpp @@ -173,7 +173,7 @@ QGeoServiceProviderFactory::createPlaceManagerEngine(const QVariantMap ¶mete } /*! - Notify the plugin when the qml engine is ready. In this moment the plugins can use it + Notify the plugin when the qml \a engine is ready. In this moment the plugins can use it to register Image Providers. The default implementation does nothing. diff --git a/src/location/places/qplaceattribute.cpp b/src/location/places/qplaceattribute.cpp index 3c4aabda..6aea68eb 100644 --- a/src/location/places/qplaceattribute.cpp +++ b/src/location/places/qplaceattribute.cpp @@ -199,9 +199,10 @@ bool QPlaceAttributePrivate::isEmpty() const A place attribute stores an additional piece of information about a \l Place that is not otherwise exposed through the \l Place type. A placeAttribute is a textual piece of data, - accessible through the \l text property, and a \l label. Both the \l text and \l label - properties are intended to be displayed to the user. placeAttributes are stored in an - \l ExtendedAttributes map with a unique key. + accessible through the \l {placeAttribute::}{text} property, and a \l {placeAttribute::}{label}. + Both the l {placeAttribute::}{text} and \l {placeAttribute::}{label} properties are intended + to be displayed to the user. placeAttributes are stored in an \l ExtendedAttributes map with + a unique key. The following example shows how to display all attributes in a list: diff --git a/src/location/places/qplacecontactdetail.cpp b/src/location/places/qplacecontactdetail.cpp index 63425527..940b330b 100644 --- a/src/location/places/qplacecontactdetail.cpp +++ b/src/location/places/qplacecontactdetail.cpp @@ -94,8 +94,9 @@ types if necessary. address. The contactDetail provides a single detail on how one could contact a \l Place. The - contactDetail consists of a \l label, which is a localized string describing the contact - method, and a \l value representing the actual contact detail. + contactDetail consists of a \l {contactDetail::}{label}, which is a localized string + describing the contact method, and a \l {contactDetail::}{value} representing the actual + contact detail. \section1 Examples @@ -186,7 +187,7 @@ bool QPlaceContactDetail::isEqual(const QPlaceContactDetail &other) const noexce */ /*! - \qmlproperty string QtLocation::ContactDetail::label + \qmlproperty string QtLocation::contactDetail::label This property holds a label describing the contact detail. @@ -214,7 +215,7 @@ void QPlaceContactDetail::setLabel(const QString &label) } /*! - \qmlproperty string QtLocation::ContactDetail::value + \qmlproperty string QtLocation::contactDetail::value This property holds the value of the contact detail which may be a phone number, an email address, a website url and so on. diff --git a/src/location/places/qplacecontent.cpp b/src/location/places/qplacecontent.cpp index 512fcabf..e0826316 100644 --- a/src/location/places/qplacecontent.cpp +++ b/src/location/places/qplacecontent.cpp @@ -66,33 +66,24 @@ QT_DEFINE_QESDP_SPECIALIZATION_DTOR(QPlaceContentPrivate) \ingroup QtLocation-places-data \since 5.6 - \brief The QPlaceContent class serves as the base class for rich content types. + \brief The QPlaceContent class holds content about places. - Rich content such as \l {QPlaceImage}{images}, \l {QPlaceReview}{reviews} - and \l {QPlaceEditorial}{editorials} inherit - from the QPlaceContent class which contains common properties such as - an attribution string and content contributor, which may take the form of a - \l {QPlaceUser}{user} and/or \l {QPlaceSupplier}{supplier}. It is possible that - a user from a supplier is contributing content, hence both fields could - be filled in simultaneously. + A QPlaceContent holds rich content such as images, reviews, or editorials, as well + as attributes about the content such as the user or supplier of the content. Content + objects might hold multiple data, e.g. an item holding a review typically includes + the user that wrote the review. Use type() to inspect the type of content a + QPlaceContent object represents, and dataTags() to see which data is held. Use value() + to get the individual data as a QVariant. \b {Note:} Some providers may \e {require} that the attribution string be displayed to the user whenever a piece of content is viewed. - Conversion between QPlaceContent and it's subclasses can be easily performed without - casting. Due to the way it has been implemented, object slicing is not an issue, - the following code is valid: - \snippet places/requesthandler.h Content conversion - - The rich content of a place is typically made available as paginated items. The ability - to convert between QPlaceContent and it's subclasses means that code which handles - the mechanics of paging can be easily shared for each of the sub types. + The rich content of a place is typically made available as paginated items. At present the QPlaceContent class is not extensible by 3rd parties. Note: The Places API considers content objects to be 'retrieve-only' objects. Submission of content to a provider is not a supported use case. - \sa QPlaceImage, QPlaceReview, QPlaceEditorial */ /*! @@ -168,7 +159,7 @@ QT_DEFINE_QESDP_SPECIALIZATION_DTOR(QPlaceContentPrivate) */ /*! - Constructs an default content object which has no type. + Constructs an content object for \a type. */ QPlaceContent::QPlaceContent(Type type) : d_ptr(new QPlaceContentPrivate(type)) diff --git a/src/location/places/qplaceratings.cpp b/src/location/places/qplaceratings.cpp index 81c342d5..6bea884c 100644 --- a/src/location/places/qplaceratings.cpp +++ b/src/location/places/qplaceratings.cpp @@ -76,18 +76,13 @@ bool QPlaceRatingsPrivate::isEmpty() const \inqmlmodule QtLocation \ingroup qml-QtLocation5-places \ingroup qml-QtLocation5-places-data - \since QtLocation 5.5 + \since QtLocation 6.5 \brief The ratings type holds place rating information. Rating information is used to describe how \e good a place is conceived to be. Typically this - information is visualized as a number of stars. The \l average property gives an aggregated - ratings value out of a possible maximum as given by the \l maximum property. - - \snippet declarative/places.qml QtQuick import - \snippet declarative/maps.qml QtLocation import - \codeline - \snippet declarative/places.qml ratings + information is visualized as a number of stars. The \l {ratings::}{average} property gives an aggregated + ratings value out of a possible maximum as given by the \l {ratings::maximum} property. */ /*! diff --git a/src/location/places/qplacesupplier.cpp b/src/location/places/qplacesupplier.cpp index fc9d8f87..f328f3bf 100644 --- a/src/location/places/qplacesupplier.cpp +++ b/src/location/places/qplacesupplier.cpp @@ -95,8 +95,6 @@ bool QPlaceSupplierPrivate::isEmpty() const Note: The Places API only supports suppliers as 'retrieve-only' objects. Submitting suppliers to a provider is not a supported use case. - \sa ImageModel, ReviewModel, EditorialModel - \section1 Example The following example shows how to create and display a supplier in QML: @@ -105,6 +103,8 @@ bool QPlaceSupplierPrivate::isEmpty() const \snippet declarative/maps.qml QtLocation import \codeline \snippet declarative/places.qml Supplier + + \sa ImageModel, ReviewModel, EditorialModel */ /*! diff --git a/src/location/places/qplaceuser.cpp b/src/location/places/qplaceuser.cpp index 6815e68f..eb2f3885 100644 --- a/src/location/places/qplaceuser.cpp +++ b/src/location/places/qplaceuser.cpp @@ -71,8 +71,6 @@ bool QPlaceUserPrivate::operator==(const QPlaceUserPrivate &other) const Each \l Place content item has an associated user who contributed the content. This type provides information about that user. - \sa ImageModel, ReviewModel, EditorialModel - \section1 Example The following example shows how to display information about the user who @@ -82,6 +80,8 @@ bool QPlaceUserPrivate::operator==(const QPlaceUserPrivate &other) const \snippet declarative/maps.qml QtLocation import \codeline \snippet declarative/places.qml EditorialModel + + \sa ImageModel, ReviewModel, EditorialModel */ /*! diff --git a/src/location/quickmapitems/qdeclarativegeomapitemview.cpp b/src/location/quickmapitems/qdeclarativegeomapitemview.cpp index 27527d35..931623c5 100644 --- a/src/location/quickmapitems/qdeclarativegeomapitemview.cpp +++ b/src/location/quickmapitems/qdeclarativegeomapitemview.cpp @@ -67,7 +67,7 @@ QT_BEGIN_NAMESPACE \section2 Example Usage This example demonstrates how to use the MapViewItem object to display - a \l{Route}{route} on a \l{Map}{map}: + a \l{route}{route} on a \l{Map}{map}: \snippet declarative/maps.qml QtQuick import \snippet declarative/maps.qml QtLocation import diff --git a/src/location/quickmapitems/qdeclarativeroutemapitem.cpp b/src/location/quickmapitems/qdeclarativeroutemapitem.cpp index b1d788ca..ea86e831 100644 --- a/src/location/quickmapitems/qdeclarativeroutemapitem.cpp +++ b/src/location/quickmapitems/qdeclarativeroutemapitem.cpp @@ -71,7 +71,7 @@ QT_BEGIN_NAMESPACE \section2 Example Usage - Here is how to draw a \l{Route}{route} on a \l{Map}{map}: + Here is how to draw a \l{route}{route} on a \l{Map}{map}: \snippet declarative/maps.qml QtQuick import \snippet declarative/maps.qml QtLocation import -- cgit v1.2.1