Doc: Add documentation for C++ classes

Currently, only QML types are documented.

Task-number: QTBUG-69686
Change-Id: Idc13bff25a154e88c6c769c0af37204573ec1118
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Teemu Holappa <teemu.holappa@qt.io>

2 files changed, 195 insertions, 0 deletions

diff --git a/src/localesettings/localefiltermodel.cpp b/src/localesettings/localefiltermodel.cpp
index 997a316..3a5d892 100644
--- a/src/localesettings/localefiltermodel.cpp
+++ b/src/localesettings/localefiltermodel.cpp
@@ -31,6 +31,33 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    \class LocaleFilterModel
+    \inmodule QtDeviceUtilities
+
+    \brief The LocaleFilterModel class provides a filtered model for the
+    available locales.
+
+    This class can be used as the model in a view that lists the available
+    locales.
+
+    \sa LocaleModel
+*/
+
+/*!
+    \property LocaleFilterModel::filter
+    \brief Holds a string that filters out the locales in the model.
+
+    The filtering process is a case-insensitive matching for whether the region
+    (country) name contains this string. The string can be taken from user
+    input.
+
+    \sa LocaleItem::country
+*/
+
+/*!
+    Creates a locale filer model with the parent \a parent.
+*/
 LocaleFilterModel::LocaleFilterModel(QObject* parent)
     :QSortFilterProxyModel(parent)
 {
@@ -39,22 +66,35 @@ LocaleFilterModel::LocaleFilterModel(QObject* parent)
     setSourceModel(localeModel);
 }
 
+/*!
+    Deletes the locale filter model.
+*/
 LocaleFilterModel::~LocaleFilterModel()
 {
 
 }
 
+/*!
+    Returns the locale filter string.
+*/
 QString LocaleFilterModel::filter() const
 {
     return m_filter;
 }
 
+/*!
+    Sets the locale filter string to \a aFilter.
+*/
 void LocaleFilterModel::setFilter(const QString& aFilter)
 {
     m_filter = aFilter;
     emit filterChanged();
 }
 
+/*!
+    Returns whether the row \a source_row has the country role and whether it is
+    found in the locale model \a source_parent.
+*/
 bool LocaleFilterModel::filterAcceptsRow( int source_row, const QModelIndex& source_parent ) const
 {
     bool ret = false;
@@ -76,6 +116,14 @@ bool LocaleFilterModel::filterAcceptsRow( int source_row, const QModelIndex& sou
     return ret;
 }
 
+/*!
+    Returns the locale item at \a row in the locale filter model.
+
+    This item can be assigned to LocaleManager::locale(), when the user selects
+    a locale from a list.
+
+    \sa LocaleItem
+*/
 QVariant LocaleFilterModel::itemFromRow(const int row) const
 {
     QModelIndex idx = index(row, 0);
@@ -91,6 +139,12 @@ QVariant LocaleFilterModel::itemFromRow(const int row) const
     return QVariant();
 }
 
+/*!
+    Returns the index for the country \a country in the locale filter model.
+
+    The index is used by item views, delegates, and selection models to locate
+    an item in the model.
+*/
 int LocaleFilterModel::indexForCountry(const QString &country) const
 {
     QAbstractItemModel *model = this->sourceModel();
diff --git a/src/localesettings/localemodel.cpp b/src/localesettings/localemodel.cpp
index 6925a02..cd411f3 100644
--- a/src/localesettings/localemodel.cpp
+++ b/src/localesettings/localemodel.cpp
@@ -35,6 +35,49 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    \class LocaleItem
+    \inmodule QtDeviceUtilities
+
+    \brief The LocaleItem class represents a locale.
+
+    This class holds the name, language, and country code of a locale.
+
+    If available, the native country name and language are used. For example,
+    \e Deutsch and \e Deutschland for the German locale.
+
+    \sa QLocale, LocaleModel
+*/
+
+/*!
+    \property LocaleItem::code
+    \brief The locale code string.
+
+    The locale code is in the format \e language_country, where \e language is
+    a lowercase, two-letter ISO 639 language code, and \e country is an
+    uppercase, two- or three-letter ISO 3166 country code.
+
+    \sa QLocale::name()
+*/
+
+/*!
+    \property LocaleItem::country
+    \brief The name of the country.
+
+    \sa QLocale::Country
+*/
+
+/*!
+    \property LocaleItem::language
+    \brief The name of the language.
+
+    \sa QLocale::Language
+*/
+
+
+/*!
+    Creates the locale item \a locale with the parent \a parent.
+*/
 LocaleItem::LocaleItem(const QLocale& locale, QObject *parent)
     :QObject(parent)
 {
@@ -50,21 +93,76 @@ LocaleItem::LocaleItem(const QLocale& locale, QObject *parent)
     }
 }
 
+/*!
+    Returns the language of the country.
+*/
 QString LocaleItem::language() const
 {
     return m_language;
 }
 
+/*!
+    Returns the name of the country.
+*/
 QString LocaleItem::country() const
 {
     return m_country;
 }
 
+/*!
+    Returns the country code of the country.
+*/
 QString LocaleItem::code() const
 {
     return m_code;
 }
 
+/*!
+    \class LocaleModel
+    \inmodule QtDeviceUtilities
+
+    \brief The LocaleModel class provides a model for the available locales.
+
+    Each item in the model has a set of data elements associated with it, each
+    with its own role. The roles are used by the view to indicate to the model
+    which type of data it needs. Custom models should return data in these
+    types.
+
+    The data in a locale model can be filtered according to the country code,
+    name, or language.
+
+    \sa LocaleItem, LocaleFilterModel
+*/
+
+/*!
+    \enum LocaleModel::Roles
+
+    This enum holds the role of the locale item.
+
+    For user roles, it is up to the developer to decide which types to use and
+    ensure that components use the correct types when accessing and setting
+    data.
+
+    \value  Language
+            The language of the country.
+    \value  Country
+            The name of the country.
+    \value  Code
+            The locale code string in the format \e language_country.
+
+    \sa Qt::UserRole
+*/
+
+/*!
+    \fn LocaleModel::addItem(LocaleItem* item)
+
+    This signal is emitted when the locale item \a item is added to the locale
+    model.
+*/
+
+/*!
+    Creates a locale model with the parent \a parent.
+*/
 LocaleModel::LocaleModel(QObject *parent)
     : QAbstractListModel(parent)
 {
@@ -79,6 +177,9 @@ LocaleModel::LocaleModel(QObject *parent)
     connect(watcher, SIGNAL(finished()), this, SLOT(modelReady()));
 }
 
+/*!
+    This signal is emitted when the locale model has been reset.
+*/
 void LocaleModel::modelReady()
 {
     beginResetModel();
@@ -88,6 +189,9 @@ void LocaleModel::modelReady()
     emit ready();
 }
 
+/*!
+    Creates the locale model \a model.
+*/
 void LocaleModel::generateModel(LocaleModel* model)
 {
     QList<QLocale> allLocales = QLocale::matchingLocales(QLocale::AnyLanguage, QLocale::AnyScript, QLocale::AnyCountry);
@@ -110,22 +214,41 @@ void LocaleModel::addNewItem(QObject *item)
    endInsertRows();
 }
 
+/*!
+    Deletes the locale model.
+*/
 LocaleModel::~LocaleModel()
 {
     qDeleteAll(m_items);
 }
 
+/*!
+    Returns an array of user roles.
+
+    \sa Roles
+*/
 QHash<int, QByteArray> LocaleModel::roleNames() const
 {
     return m_roleNames;
 }
 
+/*!
+    Returns the number of rows in the locale model.
+*/
 int LocaleModel::rowCount(const QModelIndex & parent) const
 {
     Q_UNUSED(parent);
     return m_items.count();
 }
 
+/*!
+    Returns the locale item at \a index in the locale model for \a role.
+
+    This item can be assigned to LocaleManager::locale(), when the user selects
+    a locale from a list.
+
+    \sa LocaleItem, Roles
+*/
 QVariant LocaleModel::data(const QModelIndex & index, int role) const
 {
     if (!index.isValid()) return QVariant();
@@ -150,11 +273,23 @@ QVariant LocaleModel::data(const QModelIndex & index, int role) const
     }
 }
 
+/*!
+    Returns whether the locale item has more than one languages specified.
+
+    If the language variant of the locale item if \a v1 is less than \a v2 ##?
+
+*/
 bool LocaleModel::variantLessThan(const LocaleItem* v1, const LocaleItem* v2)
 {
     return v1->language() < v2->language();
 }
 
+/*!
+    Sets the sorting order of the items in the locale model to \a order.
+
+    The sort order can be either \l {Qt::AscendingOrder}{ascending} or
+    \l {Qt::DescendingOrder}{descending}.
+*/
 void LocaleModel::sort(int column, Qt::SortOrder order)
 {
     Q_UNUSED(column);
@@ -162,6 +297,12 @@ void LocaleModel::sort(int column, Qt::SortOrder order)
     std::sort(m_items.begin(), m_items.end(), LocaleModel::variantLessThan);
 }
 
+/*!
+    Returns the index for the country \a country in the locale model.
+
+    The index is used by item views, delegates, and selection models to locate
+    an item in the model.
+*/
 QModelIndex LocaleModel::indexForCountry(const QString &country) const
 {
     for (int i = 0; i < m_items.count(); i++) {