Doc: Fix QDoc commands (QItemModelBarDataProxy)

- Use \list command for lists
- Add \brief commands for property docs
- Replace \returns with "returns"

Change-Id: I7930a9dd9ce87c61e8381a5e2c4f42c7bf0ae75a
Reviewed-by: Tomi Korpipää <tomi.korpipaa@qt.io>

1 files changed, 64 insertions, 38 deletions

diff --git a/src/datavisualization/data/qitemmodelbardataproxy.cpp b/src/datavisualization/data/qitemmodelbardataproxy.cpp
index b7c84ea7..f87016e1 100644
--- a/src/datavisualization/data/qitemmodelbardataproxy.cpp
+++ b/src/datavisualization/data/qitemmodelbardataproxy.cpp
@@ -48,21 +48,23 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
  * synchronously, unless the same frame also contains a change that causes the whole model to be
  * resolved.
  *
- * There are three ways to use mappings:
+ * Mappings can be used in the following ways:
  *
- * 1) If useModelCategories property is set to true, this proxy will map rows and
+ * \list
+ * \li If useModelCategories property is set to true, this proxy will map rows and
  *    columns of QAbstractItemModel directly to rows and columns of Q3DBars, and uses the value
  *    returned for Qt::DisplayRole as bar value by default.
  *    The value role to be used can be redefined if Qt::DisplayRole is not suitable.
  *
- * 2) For models that do not have data already neatly sorted into rows and columns, such as
+ * \li For models that do not have data already neatly sorted into rows and columns, such as
  *    QAbstractListModel based models, you can define a role from the model to map for each of row,
  *    column and value.
  *
- * 3) If you do not want to include all data contained in the model, or the autogenerated rows and
+ * \li If you do not want to include all data contained in the model, or the autogenerated rows and
  *    columns are not ordered as you wish, you can specify which rows and columns should be included
  *    and in which order by defining an explicit list of categories for either or both of rows and
  *    columns.
+ * \endlist
  *
  * For example, assume that you have a custom QAbstractItemModel for storing various monthly values
  * related to a business.
@@ -116,22 +118,22 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
 
 /*!
  * \qmlproperty string ItemModelBarDataProxy::rowRole
- * Defines the item model role to map into row category.
+ * The item model role to map into row category.
  */
 
 /*!
  * \qmlproperty string ItemModelBarDataProxy::columnRole
- * Defines the item model role to map into column category.
+ * The item model role to map into column category.
  */
 
 /*!
  * \qmlproperty string ItemModelBarDataProxy::valueRole
- * Defines the item model role to map into bar value.
+ * The item model role to map into bar value.
  */
 
 /*!
  * \qmlproperty string ItemModelBarDataProxy::rotationRole
- * Defines the item model role to map into bar rotation angle.
+ * The item model role to map into bar rotation angle.
  */
 
 /*!
@@ -150,21 +152,21 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
 
 /*!
  * \qmlproperty bool ItemModelBarDataProxy::useModelCategories
- * When set to true, the mapping ignores row and column roles and categories, and uses
+ * When set to \c true, the mapping ignores row and column roles and categories, and uses
  * the rows and columns from the model instead. Row and column headers are used for row and column
  * labels. Defaults to \c{false}.
  */
 
 /*!
  * \qmlproperty bool ItemModelBarDataProxy::autoRowCategories
- * When set to true, the mapping ignores any explicitly set row categories
+ * When set to \c true, the mapping ignores any explicitly set row categories
  * and overwrites them with automatically generated ones whenever the
  * data from the model is resolved. Defaults to \c{true}.
  */
 
 /*!
  * \qmlproperty bool ItemModelBarDataProxy::autoColumnCategories
- * When set to true, the mapping ignores any explicitly set column categories
+ * When set to \c true, the mapping ignores any explicitly set column categories
  * and overwrites them with automatically generated ones whenever the
  * data from model is resolved. Defaults to \c{true}.
  */
@@ -251,7 +253,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
 
 /*!
  * \qmlproperty ItemModelBarDataProxy.MultiMatchBehavior ItemModelBarDataProxy::multiMatchBehavior
- * This property defines how multiple matches for each row/column combination are handled.
+ * Defines how multiple matches for each row/column combination are handled.
  * Defaults to \l{QItemModelBarDataProxy::MMBLast}{ItemModelBarDataProxy.MMBLast}. The chosen
  * behavior affects both bar value and rotation.
  *
@@ -423,8 +425,12 @@ QItemModelBarDataProxy::~QItemModelBarDataProxy()
 /*!
  * \property QItemModelBarDataProxy::itemModel
  *
- * Defines item model. Does not take ownership of the model, but does connect to it to listen for
- * changes.
+ * \brief The item model.
+ */
+
+/*!
+ * Sets the item model to \a itemModel. Does not take ownership of the model,
+ * but does connect to it to listen for changes.
  */
 void QItemModelBarDataProxy::setItemModel(QAbstractItemModel *itemModel)
 {
@@ -439,7 +445,7 @@ QAbstractItemModel *QItemModelBarDataProxy::itemModel() const
 /*!
  * \property QItemModelBarDataProxy::rowRole
  *
- * Defines the row \a role for the mapping.
+ * \brief The row role for the mapping.
  */
 void QItemModelBarDataProxy::setRowRole(const QString &role)
 {
@@ -457,7 +463,7 @@ QString QItemModelBarDataProxy::rowRole() const
 /*!
  * \property QItemModelBarDataProxy::columnRole
  *
- * Defines the column \a role for the mapping.
+ * \brief The column role for the mapping.
  */
 void QItemModelBarDataProxy::setColumnRole(const QString &role)
 {
@@ -475,7 +481,7 @@ QString QItemModelBarDataProxy::columnRole() const
 /*!
  * \property QItemModelBarDataProxy::valueRole
  *
- * Defines the value \a role for the mapping.
+ * \brief The value role for the mapping.
  */
 void QItemModelBarDataProxy::setValueRole(const QString &role)
 {
@@ -493,7 +499,7 @@ QString QItemModelBarDataProxy::valueRole() const
 /*!
  * \property QItemModelBarDataProxy::rotationRole
  *
- * Defines the rotation \a role for the mapping.
+ * \brief The rotation role for the mapping.
  */
 void QItemModelBarDataProxy::setRotationRole(const QString &role)
 {
@@ -511,7 +517,7 @@ QString QItemModelBarDataProxy::rotationRole() const
 /*!
  * \property QItemModelBarDataProxy::rowCategories
  *
- * Defines the row \a categories for the mapping.
+ * \brief The row categories for the mapping.
  */
 void QItemModelBarDataProxy::setRowCategories(const QStringList &categories)
 {
@@ -529,7 +535,7 @@ QStringList QItemModelBarDataProxy::rowCategories() const
 /*!
  * \property QItemModelBarDataProxy::columnCategories
  *
- * Defines the column \a categories for the mapping.
+ * \brief The column categories for the mapping.
  */
 void QItemModelBarDataProxy::setColumnCategories(const QStringList &categories)
 {
@@ -547,7 +553,9 @@ QStringList QItemModelBarDataProxy::columnCategories() const
 /*!
  * \property QItemModelBarDataProxy::useModelCategories
  *
- * When set to true, the mapping ignores row and column roles and categories, and uses
+ * \brief Whether row and column roles and categories are used for mapping.
+ *
+ * When set to \c true, the mapping ignores row and column roles and categories, and uses
  * the rows and columns from the model instead. Defaults to \c{false}.
  */
 void QItemModelBarDataProxy::setUseModelCategories(bool enable)
@@ -566,7 +574,9 @@ bool QItemModelBarDataProxy::useModelCategories() const
 /*!
  * \property QItemModelBarDataProxy::autoRowCategories
  *
- * When set to true, the mapping ignores any explicitly set row categories
+ * \brief Whether row categories are generated automatically.
+ *
+ * When set to \c true, the mapping ignores any explicitly set row categories
  * and overwrites them with automatically generated ones whenever the
  * data from model is resolved. Defaults to \c{true}.
  */
@@ -586,7 +596,9 @@ bool QItemModelBarDataProxy::autoRowCategories() const
 /*!
  * \property QItemModelBarDataProxy::autoColumnCategories
  *
- * When set to true, the mapping ignores any explicitly set column categories
+ * \brief Whether column categories are generated automatically.
+ *
+ * When set to \c true, the mapping ignores any explicitly set column categories
  * and overwrites them with automatically generated ones whenever the
  * data from model is resolved. Defaults to \c{true}.
  */
@@ -623,7 +635,7 @@ void QItemModelBarDataProxy::remap(const QString &rowRole,
 }
 
 /*!
- * \return index of the specified \a category in row categories list.
+ * Returns the index of the specified \a category in row categories list.
  * If the row categories list is empty, -1 is returned.
  * \note If the automatic row categories generation is in use, this method will
  * not return a valid index before the data in the model is resolved for the first time.
@@ -634,7 +646,7 @@ int QItemModelBarDataProxy::rowCategoryIndex(const QString &category)
 }
 
 /*!
- * \return index of the specified \a category in column categories list.
+ * Returns the index of the specified \a category in column categories list.
  * If the category is not found, -1 is returned.
  * \note If the automatic column categories generation is in use, this method will
  * not return a valid index before the data in the model is resolved for the first time.
@@ -647,8 +659,10 @@ int QItemModelBarDataProxy::columnCategoryIndex(const QString &category)
 /*!
  * \property QItemModelBarDataProxy::rowRolePattern
  *
- * When set, a search and replace is done on the value mapped by row role before it is used as
- * a row category. This property specifies the regular expression to find the portion of the
+ * \brief Whether a search and replace is performed on the value mapped by row
+ *  role before it is used as a row category.
+ *
+ * This property specifies the regular expression to find the portion of the
  * mapped value to replace and rowRoleReplace property contains the replacement string.
  * This is useful for example in parsing row and column categories from a single
  * timestamp field in the item model.
@@ -671,8 +685,10 @@ QRegExp QItemModelBarDataProxy::rowRolePattern() const
 /*!
  * \property QItemModelBarDataProxy::columnRolePattern
  *
- * When set, a search and replace is done on the value mapped by column role before it is used
- * as a column category. This property specifies the regular expression to find the portion of the
+ * \brief Whether a search and replace is done on the value mapped by column
+ * role before it is used as a column category.
+ *
+ * This property specifies the regular expression to find the portion of the
  * mapped value to replace and columnRoleReplace property contains the replacement string.
  * This is useful for example in parsing row and column categories from
  * a single timestamp field in the item model.
@@ -695,8 +711,10 @@ QRegExp QItemModelBarDataProxy::columnRolePattern() const
 /*!
  * \property QItemModelBarDataProxy::valueRolePattern
  *
- * When set, a search and replace is done on the value mapped by value role before it is used as
- * a bar value. This property specifies the regular expression to find the portion of the
+ * \brief Whether a search and replace is done on the value mapped by value role
+ * before it is used as a bar value.
+ *
+ * This property specifies the regular expression to find the portion of the
  * mapped value to replace and valueRoleReplace property contains the replacement string.
  *
  * \sa valueRole, valueRoleReplace
@@ -717,8 +735,10 @@ QRegExp QItemModelBarDataProxy::valueRolePattern() const
 /*!
  * \property QItemModelBarDataProxy::rotationRolePattern
  *
- * When set, a search and replace is done on the value mapped by rotation role before it is used
- * as a bar rotation angle. This property specifies the regular expression to find the portion
+ * \brief Whether a search and replace is done on the value mapped by rotation
+ * role before it is used as a bar rotation angle.
+ *
+ * This property specifies the regular expression to find the portion
  * of the mapped value to replace and rotationRoleReplace property contains the replacement string.
  *
  * \sa rotationRole, rotationRoleReplace
@@ -739,7 +759,8 @@ QRegExp QItemModelBarDataProxy::rotationRolePattern() const
 /*!
  * \property QItemModelBarDataProxy::rowRoleReplace
  *
- * This property defines the replace content to be used in conjunction with rowRolePattern.
+ * \brief The replace content to be used in conjunction with rowRolePattern.
+ *
  * Defaults to empty string. For more information on how the search and replace using regular
  * expressions works, see QString::replace(const QRegExp &rx, const QString &after)
  * function documentation.
@@ -762,7 +783,8 @@ QString QItemModelBarDataProxy::rowRoleReplace() const
 /*!
  * \property QItemModelBarDataProxy::columnRoleReplace
  *
- * This property defines the replace content to be used in conjunction with columnRolePattern.
+ * \brief The replace content to be used in conjunction with columnRolePattern.
+ *
  * Defaults to empty string. For more information on how the search and replace using regular
  * expressions works, see QString::replace(const QRegExp &rx, const QString &after)
  * function documentation.
@@ -785,7 +807,8 @@ QString QItemModelBarDataProxy::columnRoleReplace() const
 /*!
  * \property QItemModelBarDataProxy::valueRoleReplace
  *
- * This property defines the replace content to be used in conjunction with valueRolePattern.
+ * \brief The replace content to be used in conjunction with valueRolePattern.
+ *
  * Defaults to empty string. For more information on how the search and replace using regular
  * expressions works, see QString::replace(const QRegExp &rx, const QString &after)
  * function documentation.
@@ -808,7 +831,9 @@ QString QItemModelBarDataProxy::valueRoleReplace() const
 /*!
  * \property QItemModelBarDataProxy::rotationRoleReplace
  *
- * This property defines the replace content to be used in conjunction with rotationRolePattern.
+ * \brief The replace content to be used in conjunction with
+ * rotationRolePattern.
+ *
  * Defaults to empty string. For more information on how the search and replace using regular
  * expressions works, see QString::replace(const QRegExp &rx, const QString &after)
  * function documentation.
@@ -831,7 +856,8 @@ QString QItemModelBarDataProxy::rotationRoleReplace() const
 /*!
  * \property QItemModelBarDataProxy::multiMatchBehavior
  *
- * This property defines how multiple matches for each row/column combination are handled.
+ * \brief How multiple matches for each row/column combination are handled.
+ *
  * Defaults to QItemModelBarDataProxy::MMBLast. The chosen behavior affects both bar value
  * and rotation.
  *