Fixed documentation for QLocale

Also added a forgotten license header for qlocale.qdoc

Reviewed-by: trustme

6 files changed, 112 insertions, 60 deletions

diff --git a/src/corelib/tools/qlocale.cpp b/src/corelib/tools/qlocale.cpp
index 4925129..2e58361 100644
--- a/src/corelib/tools/qlocale.cpp
+++ b/src/corelib/tools/qlocale.cpp
@@ -643,15 +643,12 @@ QLocale::NumberOptions QLocale::numberOptions() const
 /*!
     \since 4.8
 
-    Returns \a str quoted according to the current locale.
-
-    If \a AlternateQuotation is used for \a QuoatationStyle
-    but the locale does not provide an alternate quotation,
-    we will fallback to the parent locale.
+    Returns \a str quoted according to the current locale using the given
+    quotation \a style.
 */
-QString QLocale::quoteString(const QString &str, QuotationStyle qs) const
+QString QLocale::quoteString(const QString &str, QuotationStyle style) const
 {
-    return quoteString(&str, qs);
+    return quoteString(&str, style);
 }
 
 /*!
@@ -659,12 +656,12 @@ QString QLocale::quoteString(const QString &str, QuotationStyle qs) const
 
     \overload
 */
-QString QLocale::quoteString(const QStringRef &str, QuotationStyle qs) const
+QString QLocale::quoteString(const QStringRef &str, QuotationStyle style) const
 {
 #ifndef QT_NO_SYSTEMLOCALE
     if (d() == systemPrivate()) {
         QVariant res;
-        if (qs == QLocale::StandardQuotation)
+        if (style == QLocale::StandardQuotation)
             res = systemLocale()->query(QSystemLocale::StringToStandardQuotation, QVariant::fromValue(str));
         else
             res = systemLocale()->query(QSystemLocale::StringToAlternateQuotation, QVariant::fromValue(str));
@@ -674,7 +671,7 @@ QString QLocale::quoteString(const QStringRef &str, QuotationStyle qs) const
     }
 #endif
 
-    if (qs == QLocale::StandardQuotation)
+    if (style == QLocale::StandardQuotation)
         return QChar(d()->m_quotation_start) % str % QChar(d()->m_quotation_end);
     else
         return QChar(d()->m_alternate_quotation_start) % str % QChar(d()->m_alternate_quotation_end);
@@ -2847,41 +2844,12 @@ QString QLocale::currencySymbol(QLocale::CurrencySymbolFormat format) const
 }
 
 /*!
-    \fn QString QLocale::toCurrencyString(short, const QString &) const
-    \since 4.8
-    \overload
-*/
-
-/*!
-    \fn QString QLocale::toCurrencyString(ushort, const QString &) const
-    \since 4.8
-    \overload
-*/
-
-/*!
-    \fn QString QLocale::toCurrencyString(int, const QString &) const
-    \since 4.8
-    \overload
-*/
-
-/*!
-    \fn QString QLocale::toCurrencyString(uint, const QString &) const
-    \since 4.8
-    \overload
-*/
-/*!
-    \fn QString QLocale::toCurrencyString(float, const QString &) const
-    \since 4.8
-    \overload
-*/
-
-/*!
     \since 4.8
 
     Returns a localized string representation of \a value as a currency.
     If the \a symbol is provided it is used instead of the default currency symbol.
 
-    \sa currencySymbol
+    \sa currencySymbol()
 */
 QString QLocale::toCurrencyString(qlonglong value, const QString &symbol) const
 {
diff --git a/src/corelib/tools/qlocale.h b/src/corelib/tools/qlocale.h
index a5d5a17..37c43b0 100644
--- a/src/corelib/tools/qlocale.h
+++ b/src/corelib/tools/qlocale.h
@@ -727,8 +727,8 @@ public:
     NumberOptions numberOptions() const;
 
     enum QuotationStyle { StandardQuotation, AlternateQuotation };
-    QString quoteString(const QString &str, QuotationStyle qs = StandardQuotation) const;
-    QString quoteString(const QStringRef &str, QuotationStyle qs = StandardQuotation) const;
+    QString quoteString(const QString &str, QuotationStyle style = StandardQuotation) const;
+    QString quoteString(const QStringRef &str, QuotationStyle style = StandardQuotation) const;
 
 //private:                        // this should be private, but can't be
     struct Data {
diff --git a/src/corelib/tools/qlocale.qdoc b/src/corelib/tools/qlocale.qdoc
index 20f546d..dcabcd9 100644
--- a/src/corelib/tools/qlocale.qdoc
+++ b/src/corelib/tools/qlocale.qdoc
@@ -1,3 +1,29 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of this
+** file.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
 
 /*!
     \class QLocale
@@ -708,7 +734,7 @@
   \value PMText a string that represents the system PM designator associated with a 12-hour clock.
   \value FirstDayOfWeek a Qt::DayOfWeek enum specifiying the first day of the week
   \value CurrencySymbol a string that represents a currency in a format QLocale::CurrencyFormat.
-  \value CurrencyToString a localized string representation of a number with a currency symbol.
+  \value CurrencyToString a localized string representation of a number with a currency symbol. Converts a QSystemLocale::CurrencyToStringArgument stored in the in variant to a QString.
   \value UILanguages a list of strings representing locale names that could be used for UI translation.
   \value StringToStandardQuotation a QString containing a quoted version of the string ref stored in the in variant using standard quotes.
   \value StringToAlternateQuotation a QString containing a quoted version of the string ref stored in the in variant using alternate quotes.
@@ -717,6 +743,52 @@
 */
 
 /*!
+    \fn QLocale QSystemLocale::fallbackLocale() const
+
+    \since 4.6
+    Returns the fallback locale obtained from the system.
+*/
+
+/*!
+    \fn QVariant QSystemLocale::query(QueryType type, QVariant in = QVariant()) const
+
+    Generic query method for locale data. Provides indirection.
+    Denotes the \a type of the query
+    with \a in as input data depending on the query.
+
+    \sa QSystemLocale::QueryType
+*/
+
+/*!
+    \class QSystemLocale::CurrencyToStringArgument
+
+    A helper class that provides arguments for the QSystemLocale::query()
+    function with query type QSystemLocale::CurrencyToString.
+
+    \sa QSystemLocale::QueryType
+    \since 4.8
+*/
+
+/*!
+    \fn QSystemLocale::CurrencyToStringArgument::CurrencyToStringArgument()
+    \internal
+*/
+/*!
+    \variable QSystemLocale::CurrencyToStringArgument::value
+
+    An input value that should be converted to its string representation.
+    Contains one of QVariant::LongLong, QVariant::ULongLong or QVariant::Double
+    types.
+*/
+/*!
+    \variable QSystemLocale::CurrencyToStringArgument::symbol
+
+    An optional argument containing a currency symbol to be used in the
+    currency string.
+*/
+
+
+/*!
 \fn QString QLocale::toString(short i) const
 
 \overload
@@ -773,3 +845,32 @@
 
 \sa toDouble()
 */
+
+/*!
+    \fn QString QLocale::toCurrencyString(short value, const QString &symbol) const
+    \since 4.8
+    \overload
+*/
+
+/*!
+    \fn QString QLocale::toCurrencyString(ushort value, const QString &symbol) const
+    \since 4.8
+    \overload
+*/
+
+/*!
+    \fn QString QLocale::toCurrencyString(int value, const QString &symbol) const
+    \since 4.8
+    \overload
+*/
+
+/*!
+    \fn QString QLocale::toCurrencyString(uint value, const QString &symbol) const
+    \since 4.8
+    \overload
+*/
+/*!
+    \fn QString QLocale::toCurrencyString(float value, const QString &symbol) const
+    \since 4.8
+    \overload
+*/
diff --git a/src/corelib/tools/qlocale_symbian.cpp b/src/corelib/tools/qlocale_symbian.cpp
index 4d84de5..85ffb9e 100644
--- a/src/corelib/tools/qlocale_symbian.cpp
+++ b/src/corelib/tools/qlocale_symbian.cpp
@@ -825,13 +825,6 @@ QLocale QSystemLocale::fallbackLocale() const
     return QLocale(locale);
 }
 
-/*!
-    Generic query method for locale data. Provides indirection.
-    Denotes the \a type of the query
-    with \a in as input data depending on the query.
-
-    \sa QSystemLocale::QueryType
-*/
 QVariant QSystemLocale::query(QueryType type, QVariant in = QVariant()) const
 {
     switch(type) {
diff --git a/src/corelib/tools/qlocale_unix.cpp b/src/corelib/tools/qlocale_unix.cpp
index 74c8c85..72eefd5 100644
--- a/src/corelib/tools/qlocale_unix.cpp
+++ b/src/corelib/tools/qlocale_unix.cpp
@@ -91,9 +91,6 @@ Q_GLOBAL_STATIC(QSystemLocaleData, qSystemLocaleData)
 #endif
 
 #ifndef QT_NO_SYSTEMLOCALE
-/*!
-    \internal
-*/
 QLocale QSystemLocale::fallbackLocale() const
 {
     QByteArray lang = qgetenv("LC_ALL");
@@ -104,9 +101,6 @@ QLocale QSystemLocale::fallbackLocale() const
     return QLocale(QLatin1String(lang));
 }
 
-/*!
-    \internal
-*/
 QVariant QSystemLocale::query(QueryType type, QVariant in) const
 {
     QSystemLocaleData *d = qSystemLocaleData();
diff --git a/src/corelib/tools/qlocale_win.cpp b/src/corelib/tools/qlocale_win.cpp
index cb191f2..ec63d1a 100644
--- a/src/corelib/tools/qlocale_win.cpp
+++ b/src/corelib/tools/qlocale_win.cpp
@@ -494,10 +494,6 @@ QStringList winUILanguages()
 
 #ifndef QT_NO_SYSTEMLOCALE
 
-/*!
-    \since 4.6
-    Returns the fallback locale obtained from the system.
- */
 QLocale QSystemLocale::fallbackLocale() const
 {
     return QLocale(QString::fromLatin1(getWinLocaleName()));