Places QML API documentation is incomplete

Attempt at fixing QTBUG-24438

The QML documentation changes are:

* ContactDetail, EditorialModel, ImageModel, Supplier, User now have an example
* errorString method documented for CategoryModel, PlaceRecommendationModel, PlaceSearchSuggestionModel
* Added documentation for PlaceSearchModel::SearchResultType.
* Documented ExtendedAttributes::onValueChanged signal.

Change-Id: I37dbee7107713996592a98abade26d32f7cc9b0e
Reviewed-by: Alex <alex.blasche@nokia.com>
Reviewed-by: abcd <amos.choy@nokia.com>

11 files changed, 253 insertions, 4 deletions

diff --git a/doc/src/snippets/declarative/places.qml b/doc/src/snippets/declarative/places.qml
index ed16db0c..815de856 100644
--- a/doc/src/snippets/declarative/places.qml
+++ b/doc/src/snippets/declarative/places.qml
@@ -180,6 +180,112 @@ Item {
     }
     //! [SearchSuggestionModel]
 
+    //! [EditorialModel]
+    EditorialModel {
+        id: editorialModel
+        batchSize: 3
+        place: place
+    }
+
+    ListView {
+        model: editorialModel
+        delegate: Item {
+            anchors.fill: parent
+
+            Column {
+                width: parent.width
+                clip: true
+
+                Text {
+                    text: title
+                    width: parent.width
+                    wrapMode: Text.WordWrap
+                    font.pixelSize: 24
+                }
+
+                Text {
+                    text: text
+                    width: parent.width
+                    wrapMode: Text.WordWrap
+                    font.pixelSize: 20
+                }
+
+                Row {
+                    Image {
+                        width: 16
+                        height: 16
+
+                        source: supplier.icon.url(Qt.size(width, height), Icon.List)
+                    }
+
+                    Text {
+                        text: "Provided by " + supplier.name
+                        font.pixelSize: 16
+                    }
+                }
+
+                Text {
+                    text: "Contributed by " + user.name
+                    font.pixelSize: 16
+                }
+
+                Text {
+                    text: attribution
+                    font.pixelSize: 8
+                }
+            }
+        }
+    }
+    //! [EditorialModel]
+
+    //! [ImageModel]
+    ImageModel {
+        id: imageModel
+        batchSize: 3
+        place: place
+    }
+
+    ListView {
+        anchors.top: parent.top
+        anchors.bottom: position.top
+        width: parent.width
+        spacing: 10
+
+        model: imageModel
+        orientation: ListView.Horizontal
+        snapMode: ListView.SnapOneItem
+
+        delegate: Item {
+            width: listView.width
+            height: listView.height
+
+            Image {
+                anchors.fill: parent
+                source: url
+                fillMode: Image.PreserveAspectFit
+            }
+
+            Text {
+                text: supplier.name + "\n" + supplier.url
+                width: parent.width
+                anchors.bottom: parent.bottom
+            }
+        }
+    }
+    //! [ImageModel]
+
+    //! [Supplier]
+    Supplier {
+        id: placeSupplier
+        name: "Example"
+        url: "http://www.example.com/"
+    }
+
+    Text {
+        text: "This place is was provided by " + placeSupplier.name + "\n" + placeSupplier.url
+    }
+    //! [Supplier]
+
     //! [Ratings]
     Text {
         text: "This place is rated " + place.ratings.average + " out of " + place.ratings.maximum + " stars."
@@ -225,7 +331,6 @@ Item {
     }
     //! [ContactDetails write multiple]
 
-
     //! [ContactDetails phoneList]
     ListView {
         model: place.contactDetails.phone;
diff --git a/src/imports/location/declarativeplaces/qdeclarativecontactdetail.cpp b/src/imports/location/declarativeplaces/qdeclarativecontactdetail.cpp
index b966eba2..df61e57d 100644
--- a/src/imports/location/declarativeplaces/qdeclarativecontactdetail.cpp
+++ b/src/imports/location/declarativeplaces/qdeclarativecontactdetail.cpp
@@ -65,6 +65,8 @@
         \o website
     \endlist
 
+    \section1 Examples
+
     The following example shows how to access all \l {QtLocation5::ContactDetail}{ContactDetails}
     and print them to the console:
 
@@ -110,6 +112,18 @@
     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.
+
+    \section1 Examples
+
+    The following example demonstrates how to assign a single phone number to a place in javascript:
+    \snippet snippets/declarative/places.qml  ContactDetails write single
+
+    The following demonstrates how to assign multiple phone numbers to a place in javascript:
+    \snippet snippets/declarative/places.qml  ContactDetails write multiple
+
+    Note, due to limitations of the QDeclarativePropertyMap, it is not possible
+    to declaratively specify the contact details in QML, it can only be accomplished
+    via javascript.
 */
 QDeclarativeContactDetail::QDeclarativeContactDetail(QObject *parent)
     : QObject(parent)
diff --git a/src/imports/location/declarativeplaces/qdeclarativeplaceattribute.cpp b/src/imports/location/declarativeplaces/qdeclarativeplaceattribute.cpp
index f35356c6..96b041d3 100644
--- a/src/imports/location/declarativeplaces/qdeclarativeplaceattribute.cpp
+++ b/src/imports/location/declarativeplaces/qdeclarativeplaceattribute.cpp
@@ -96,6 +96,13 @@
 */
 
 /*!
+    \qmlsignal void ExtendedAttributes::onValueChanged(string key, variant value)
+
+    This signal is raised when the set of attributes changes. \a key is the key
+    corresponding to the \l value that was changed.
+*/
+
+/*!
     \qmlclass PlaceAttribute QDeclarativePlaceAttribute
     \inqmlmodule QtLocation 5
     \ingroup qml-QtLocation5-places
diff --git a/src/imports/location/declarativeplaces/qdeclarativeplaceeditorialmodel.cpp b/src/imports/location/declarativeplaces/qdeclarativeplaceeditorialmodel.cpp
index 14af7d20..d8913972 100644
--- a/src/imports/location/declarativeplaces/qdeclarativeplaceeditorialmodel.cpp
+++ b/src/imports/location/declarativeplaces/qdeclarativeplaceeditorialmodel.cpp
@@ -93,6 +93,16 @@ QT_BEGIN_NAMESPACE
             \o string
             \o Attribution text which must be displayed when displaying the editorial.
     \endtable
+
+    \section Example
+
+    The following example shows how to display editorials for a place:
+
+    \snippet snippets/declarative/places.qml QtQuick import
+    \snippet snippets/declarative/places.qml QtLocation import
+    \codeline
+    \snippet snippets/declarative/places.qml EditorialModel
+
 */
 
 /*!
diff --git a/src/imports/location/declarativeplaces/qdeclarativeplaceimagemodel.cpp b/src/imports/location/declarativeplaces/qdeclarativeplaceimagemodel.cpp
index dd682c35..9284ea5c 100644
--- a/src/imports/location/declarativeplaces/qdeclarativeplaceimagemodel.cpp
+++ b/src/imports/location/declarativeplaces/qdeclarativeplaceimagemodel.cpp
@@ -93,6 +93,16 @@ QT_BEGIN_NAMESPACE
             \o string
             \o Attribution text which must be displayed when displaying the editorial.
     \endtable
+
+
+    \section1 Example
+
+    The following example shows how to display images for a place:
+
+    \snippet snippets/declarative/places.qml QtQuick import
+    \snippet snippets/declarative/places.qml QtLocation import
+    \codeline
+    \snippet snippets/declarative/places.qml ImageModel
 */
 
 /*!
diff --git a/src/imports/location/declarativeplaces/qdeclarativeplaceuser.cpp b/src/imports/location/declarativeplaces/qdeclarativeplaceuser.cpp
index f61960ca..5ef304f8 100644
--- a/src/imports/location/declarativeplaces/qdeclarativeplaceuser.cpp
+++ b/src/imports/location/declarativeplaces/qdeclarativeplaceuser.cpp
@@ -56,6 +56,16 @@ QT_USE_NAMESPACE
     provides information about that user.
 
     \sa ImageModel, ReviewModel, EditorialModel
+
+    \section1 Example
+
+    The following example shows how to display information about the user who
+    submitted an editorial:
+
+    \snippet snippets/declarative/places.qml QtQuick import
+    \snippet snippets/declarative/places.qml QtLocation import
+    \codeline
+    \snippet snippets/declarative/places.qml EditorialModel
 */
 
 QDeclarativePlaceUser::QDeclarativePlaceUser(QObject* parent)
diff --git a/src/imports/location/declarativeplaces/qdeclarativerecommendationmodel.cpp b/src/imports/location/declarativeplaces/qdeclarativerecommendationmodel.cpp
index 8c633aa6..12758922 100644
--- a/src/imports/location/declarativeplaces/qdeclarativerecommendationmodel.cpp
+++ b/src/imports/location/declarativeplaces/qdeclarativerecommendationmodel.cpp
@@ -201,6 +201,16 @@ QT_USE_NAMESPACE
     Clears the current place recommendations stored in the model.
 */
 
+/*!
+    \qmlproperty string QtLocation5::PlaceRecommendationModel::errorString
+
+    This read-only property holds the textual presentation of latest place recommendation model error.
+    If no error has occurred or if the model was cleared, an empty string is returned.
+
+    An empty string may also be returned if an error occurred which has no associated
+    textual representation.
+*/
+
 QDeclarativeRecommendationModel::QDeclarativeRecommendationModel(QObject *parent)
 :   QDeclarativeResultModelBase(parent)
 {
diff --git a/src/imports/location/declarativeplaces/qdeclarativesearchresultmodel.cpp b/src/imports/location/declarativeplaces/qdeclarativesearchresultmodel.cpp
index 13d744e3..f5cc282e 100644
--- a/src/imports/location/declarativeplaces/qdeclarativesearchresultmodel.cpp
+++ b/src/imports/location/declarativeplaces/qdeclarativesearchresultmodel.cpp
@@ -110,6 +110,24 @@ QT_USE_NAMESPACE
                the search term.
     \endtable
 
+    \section2 Search result types
+
+    The \c type role can take on the following values:
+
+    \table
+        \row
+            \o PlaceSearchModel.PlaceResult
+            \o The search result contains a place.
+        \row
+            \o PlaceSearchModel.CorrectionResult
+            \o The search result contains a search term correction.
+        \row
+            \o PlaceSearchModel.UnknownSearchResult
+            \o The contents of the search result are unknown.
+    \endtable
+
+    \section1 Example
+
     The following example shows how to use the PlaceSearchModel to search for Pizza restaurants in
     close proximity of a given position.
 
@@ -224,6 +242,16 @@ QT_USE_NAMESPACE
     Clears the current search results stored in the model.
 */
 
+/*!
+    \qmlproperty string QtLocation5::PlaceSearchModel::errorString
+
+    This read-only property holds the textual presentation of latest place search model error.
+    If no error has occurred or if the model was cleared an empty string is returned.
+
+    An empty string may also be returned if an error occurred which has no associated
+    textual representation.
+*/
+
 QDeclarativeSearchResultModel::QDeclarativeSearchResultModel(QObject *parent)
 :   QDeclarativeResultModelBase(parent)
 {
diff --git a/src/imports/location/declarativeplaces/qdeclarativesearchsuggestionmodel.cpp b/src/imports/location/declarativeplaces/qdeclarativesearchsuggestionmodel.cpp
index b4b70737..3e8a2c56 100644
--- a/src/imports/location/declarativeplaces/qdeclarativesearchsuggestionmodel.cpp
+++ b/src/imports/location/declarativeplaces/qdeclarativesearchsuggestionmodel.cpp
@@ -172,6 +172,17 @@ QT_USE_NAMESPACE
     Clears the current search suggestions stored in the model.
 */
 
+
+/*!
+    \qmlproperty string QtLocation5::PlaceSearchSuggestionModel::errorString
+
+    This read-only property holds the textual presentation of latest search suggestion model error.
+    If no error has occurred, or if the model was cleared, an empty string is returned.
+
+    An empty string may also be returned if an error occurred which has no associated
+    textual representation.
+*/
+
 QDeclarativeSearchSuggestionModel::QDeclarativeSearchSuggestionModel(QObject *parent)
 :   QDeclarativeSearchModelBase(parent)
 {
diff --git a/src/imports/location/declarativeplaces/qdeclarativesupplier.cpp b/src/imports/location/declarativeplaces/qdeclarativesupplier.cpp
index 5c76f2ce..ad659008 100644
--- a/src/imports/location/declarativeplaces/qdeclarativesupplier.cpp
+++ b/src/imports/location/declarativeplaces/qdeclarativesupplier.cpp
@@ -52,10 +52,25 @@ QT_USE_NAMESPACE
     \ingroup qml-QtLocation5-places-data
     \since QtLocation 5.0
 
-    \brief The Supplier element holds supplier data.
+    \brief The Supplier element holds data regarding the supplier of a place,
+    a place's image, review, or editorial.
 
-    Supplier contains many properties holding data of the supplier like name,
-    id, etc.
+    Each instance represents a set of data about a supplier, which can include
+    supplier's name, url and icon.  The supplier is typically a business or organization.
+
+    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:
+
+    \snippet snippets/declarative/places.qml QtQuick import
+    \snippet snippets/declarative/places.qml QtLocation import
+    \codeline
+    \snippet snippets/declarative/places.qml Supplier
 */
 
 QDeclarativeSupplier::QDeclarativeSupplier(QObject* parent)
diff --git a/src/imports/location/declarativeplaces/qdeclarativesupportedcategoriesmodel.cpp b/src/imports/location/declarativeplaces/qdeclarativesupportedcategoriesmodel.cpp
index 1f7c057d..f468e036 100644
--- a/src/imports/location/declarativeplaces/qdeclarativesupportedcategoriesmodel.cpp
+++ b/src/imports/location/declarativeplaces/qdeclarativesupportedcategoriesmodel.cpp
@@ -99,6 +99,35 @@ QT_USE_NAMESPACE
     list.  The default is true.
 */
 
+/*!
+    \qmlmethod string QtLocation5::CategoryModel::data(ModelIndex index, int role)
+    \internal
+
+    This method retrieves the the model's data per \a index and \a role.
+*/
+
+/*!
+    \qmlproperty string QtLocation5::CategoryModel::errorString
+
+    This read-only property holds the textual presentation of latest category model error.
+    If no error has occurred, an empty string is returned.
+
+    An empty string may also be returned if an error occurred which has no associated
+    textual representation.
+*/
+
+/*!
+    \qmlproperty enumeration QtLocation5::CategoryModel::status
+
+    This read-only property holds the current status of the model.
+
+    \list
+    \o CategoryModel.Ready - Category request(s) have finished successfully.
+    \o CategoryModel.Updating - Category request has been issued but not yet finished
+    \o CategoryModel.Error - An error has occurred, details are in \l errorString
+    \endlist
+*/
+
 QDeclarativeSupportedCategoriesModel::QDeclarativeSupportedCategoriesModel(QObject *parent)
 :   QAbstractItemModel(parent), m_plugin(0), m_hierarchical(true), m_complete(false)
 {