Consolidate documentation of floating-point formatting code

Move the documentation of the format and precision parameters to
QLocale::toString(double, char, int), reference it from various
QString methods (instead of repeating there and referencing one of
those from QLocale). Add brief first lines for various documentation
comments.

Mention the special handling of negative precision in the moved
documentation. Mention QLocale::FloatingPointShortest, add its type to
\sa lines of methods it affects. Change a comment on some code
implementing its special treatment to make clear that it does apply to
'e' and 'f' formats, not only to 'g', even though it has no overt
special handling in that code; and update docs to report the
undocumented behavior the comment previously described.

Document how infinity and NaN are represented. Be somewhat more
consistent about single-quoting the format names where referred to and
applying \c to character constants.

Make clear what things are different between different methods using
these parameters. Reference QString::number() from QByteArray's
relevant methods, since they share its quirks.

In the process, rename the format and precision parameters of relevant
functions so they're consistently named, replacing a mixture of
abbreviated forms.

Pick-to: 6.2
Change-Id: I077521b30346000e4b4f6968a8e750e934f72937
Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>

7 files changed, 175 insertions, 201 deletions

diff --git a/src/corelib/text/qbytearray.cpp b/src/corelib/text/qbytearray.cpp
index 32e10b9512..d97375897d 100644
--- a/src/corelib/text/qbytearray.cpp
+++ b/src/corelib/text/qbytearray.cpp
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2020 The Qt Company Ltd.
+** Copyright (C) 2021 The Qt Company Ltd.
 ** Copyright (C) 2016 Intel Corporation.
 ** Copyright (C) 2019 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Giuseppe D'Angelo <giuseppe.dangelo@kdab.com>
 ** Contact: https://www.qt.io/licensing/
@@ -899,17 +899,18 @@ QByteArray qUncompress(const uchar* data, qsizetype nbytes)
     \section2 Spacing Characters
 
     A frequent requirement is to remove spacing characters from a byte array
-    ('\\n', '\\t', ' ', etc.). If you want to remove spacing from both ends of a
-    QByteArray, use trimmed(). If you want to also replace each run of spacing
-    characters with a single space character within the byte array, use
+    (\c{'\n'}, \c{'\t'}, \c{' '}, etc.). If you want to remove spacing from both
+    ends of a QByteArray, use trimmed(). If you want to also replace each run of
+    spacing characters with a single space character within the byte array, use
     simplified(). Only ASCII spacing characters are recognized for these
     purposes.
 
     \section2 Number-String Conversions
 
-    Functions that perform conversions between numeric data types and strings
-    are performed in the C locale, regardless of the user's locale settings. Use
-    QLocale to perform locale-aware conversions between numbers and strings.
+    Functions that perform conversions between numeric data types and string
+    representations are performed in the C locale, regardless of the user's
+    locale settings. Use QLocale to perform locale-aware conversions between
+    numbers and strings.
 
     \section2 Character Case
 
@@ -923,7 +924,7 @@ QByteArray qUncompress(const uchar* data, qsizetype nbytes)
     This issue does not apply to \l{QString}s since they represent characters
     using Unicode.
 
-    \sa  QByteArrayView, QString, QBitArray
+    \sa QByteArrayView, QString, QBitArray
 */
 
 /*!
@@ -3863,8 +3864,10 @@ QByteArray QByteArray::toBase64(Base64Options options) const
 /*!
     \fn QByteArray &QByteArray::setNum(int n, int base)
 
-    Sets the byte array to the printed value of \a n in base \a base (ten by
-    default) and returns a reference to the byte array. Bases 2 through 36 are
+    Represent the whole number \a n as text.
+
+    Sets this byte array to a string representing \a n in base \a base (ten by
+    default) and returns a reference to this byte array. Bases 2 through 36 are
     supported, using letters for digits beyond 9; A is ten, B is eleven and so
     on.
 
@@ -3975,56 +3978,39 @@ QByteArray &QByteArray::setNum(qulonglong n, int base)
 /*!
     \overload
 
-    Sets the byte array to the printed value of \a n, formatted in format
-    \a f with precision \a prec, and returns a reference to the
-    byte array.
-
-    The format \a f can be any of the following:
-
-    \table
-    \header \li Format \li Meaning
-    \row \li \c e \li format as [-]9.9e[+|-]999
-    \row \li \c E \li format as [-]9.9E[+|-]999
-    \row \li \c f \li format as [-]9.9
-    \row \li \c g \li use \c e or \c f format, whichever is the most concise
-    \row \li \c G \li use \c E or \c f format, whichever is the most concise
-    \endtable
+    Represent the floating-point number \a n as text.
 
-    With 'e', 'E', and 'f', \a prec is the number of digits after the
-    decimal point. With 'g' and 'G', \a prec is the maximum number of
-    significant digits (trailing zeroes are omitted).
+    Sets this byte array to a string representating \a n, with a given \a format
+    and \a precision (with the same meanings as for \l {QString::number(double,
+    char, int)}), and returns a reference to this byte array.
 
-    \note The format of the number is not localized; the default C locale is
-    used regardless of the user's locale. Use QLocale to perform locale-aware
-    conversions between numbers and strings.
-
-    \sa toDouble()
+    \sa toDouble(), QLocale::FloatingPointPrecisionOption
 */
 
-QByteArray &QByteArray::setNum(double n, char f, int prec)
+QByteArray &QByteArray::setNum(double n, char format, int precision)
 {
-    return *this = QByteArray::number(n, f, prec);
+    return *this = QByteArray::number(n, format, precision);
 }
 
 /*!
-    \fn QByteArray &QByteArray::setNum(float n, char f, int prec)
+    \fn QByteArray &QByteArray::setNum(float n, char format, int precision)
     \overload
 
-    Sets the byte array to the printed value of \a n, formatted in format
-    \a f with precision \a prec, and returns a reference to the
-    byte array.
+    Represent the floating-point number \a n as text.
 
-    \note The format of the number is not localized; the default C locale is
-    used regardless of the user's locale. Use QLocale to perform locale-aware
-    conversions between numbers and strings.
+    Sets this byte array to a string representating \a n, with a given \a format
+    and \a precision (with the same meanings as for \l {QString::number(double,
+    char, int)}), and returns a reference to this byte array.
 
     \sa toFloat()
 */
 
 /*!
-    Returns a byte array containing the printed value of the number \a n to base
-    \a base (ten by default). Bases 2 through 36 are supported, using letters
-    for digits beyond 9: A is ten, B is eleven and so on.
+    Returns a byte-array representing the whole number \a n as text.
+
+    Returns a byte array containing a string representating \a n, using the
+    specified \a base (ten by default). Bases 2 through 36 are supported, using
+    letters for digits beyond 9: A is ten, B is eleven and so on.
 
     Example:
     \snippet code/src_corelib_text_qbytearray.cpp 41
@@ -4104,45 +4090,26 @@ QByteArray QByteArray::number(qulonglong n, int base)
 
 /*!
     \overload
+    Returns a byte-array representing the floating-point number \a n as text.
 
-    Returns a byte array that contains the printed value of \a n,
-    formatted in format \a f with precision \a prec.
-
-    Argument \a n is formatted according to the \a f format specified,
-    which is \c g by default, and can be any of the following:
-
-    \table
-    \header \li Format \li Meaning
-    \row \li \c e \li format as [-]9.9e[+|-]999
-    \row \li \c E \li format as [-]9.9E[+|-]999
-    \row \li \c f \li format as [-]9.9
-    \row \li \c g \li use \c e or \c f format, whichever is the most concise
-    \row \li \c G \li use \c E or \c f format, whichever is the most concise
-    \endtable
-
-    With 'e', 'E', and 'f', \a prec is the number of digits after the
-    decimal point. With 'g' and 'G', \a prec is the maximum number of
-    significant digits (trailing zeroes are omitted).
+    Returns a byte array containing a string representing \a n, with a given \a
+    format and \a precision, with the same meanings as for \l
+    {QString::number(double, char, int)}. For example:
 
     \snippet code/src_corelib_text_qbytearray.cpp 42
 
-    \note The format of the number is not localized; the default C locale is
-    used regardless of the user's locale. Use QLocale to perform locale-aware
-    conversions between numbers and strings.
-
-    \sa toDouble()
+    \sa toDouble(), QLocale::FloatingPointPrecisionOption
 */
-QByteArray QByteArray::number(double n, char f, int prec)
+QByteArray QByteArray::number(double n, char format, int precision)
 {
     QLocaleData::DoubleForm form = QLocaleData::DFDecimal;
     uint flags = QLocaleData::ZeroPadExponent;
 
-    char lower = asciiLower(uchar(f));
-    if (f != lower)
+    char lower = asciiLower(uchar(format));
+    if (format != lower)
         flags |= QLocaleData::CapitalEorX;
-    f = lower;
 
-    switch (f) {
+    switch (lower) {
         case 'f':
             form = QLocaleData::DFDecimal;
             break;
@@ -4154,12 +4121,12 @@ QByteArray QByteArray::number(double n, char f, int prec)
             break;
         default:
 #if defined(QT_CHECK_RANGE)
-            qWarning("QByteArray::setNum: Invalid format char '%c'", f);
+            qWarning("QByteArray::setNum: Invalid format char '%c'", format);
 #endif
             break;
     }
 
-    return QLocaleData::c()->doubleToString(n, prec, form, -1, flags).toUtf8();
+    return QLocaleData::c()->doubleToString(n, precision, form, -1, flags).toUtf8();
 }
 
 /*!
diff --git a/src/corelib/text/qbytearray.h b/src/corelib/text/qbytearray.h
index 2d614f1fe0..10fa1e68ba 100644
--- a/src/corelib/text/qbytearray.h
+++ b/src/corelib/text/qbytearray.h
@@ -375,8 +375,8 @@ public:
     inline QByteArray &setNum(ulong, int base = 10);
     QByteArray &setNum(qlonglong, int base = 10);
     QByteArray &setNum(qulonglong, int base = 10);
-    inline QByteArray &setNum(float, char f = 'g', int prec = 6);
-    QByteArray &setNum(double, char f = 'g', int prec = 6);
+    inline QByteArray &setNum(float, char format = 'g', int precision = 6);
+    QByteArray &setNum(double, char format = 'g', int precision = 6);
     QByteArray &setRawData(const char *a, qsizetype n);
 
     [[nodiscard]] static QByteArray number(int, int base = 10);
@@ -385,7 +385,7 @@ public:
     [[nodiscard]] static QByteArray number(ulong, int base = 10);
     [[nodiscard]] static QByteArray number(qlonglong, int base = 10);
     [[nodiscard]] static QByteArray number(qulonglong, int base = 10);
-    [[nodiscard]] static QByteArray number(double, char f = 'g', int prec = 6);
+    [[nodiscard]] static QByteArray number(double, char format = 'g', int precision = 6);
     [[nodiscard]] static QByteArray fromRawData(const char *data, qsizetype size)
     {
         return QByteArray(DataPointer(nullptr, const_cast<char *>(data), size));
@@ -609,8 +609,8 @@ inline QByteArray &QByteArray::setNum(long n, int base)
 { return setNum(qlonglong(n), base); }
 inline QByteArray &QByteArray::setNum(ulong n, int base)
 { return setNum(qulonglong(n), base); }
-inline QByteArray &QByteArray::setNum(float n, char f, int prec)
-{ return setNum(double(n),f,prec); }
+inline QByteArray &QByteArray::setNum(float n, char format, int precision)
+{ return setNum(double(n), format, precision); }
 
 inline std::string QByteArray::toStdString() const
 { return std::string(constData(), length()); }
diff --git a/src/corelib/text/qlocale.cpp b/src/corelib/text/qlocale.cpp
index ca4f7733f3..52d3938516 100644
--- a/src/corelib/text/qlocale.cpp
+++ b/src/corelib/text/qlocale.cpp
@@ -1072,7 +1072,7 @@ size_t qHash(const QLocale &key, size_t seed) noexcept
     Sets the \a options related to number conversions for this
     QLocale instance.
 
-    \sa numberOptions()
+    \sa numberOptions(), FloatingPointPrecisionOption
 */
 void QLocale::setNumberOptions(NumberOptions options)
 {
@@ -1088,7 +1088,7 @@ void QLocale::setNumberOptions(NumberOptions options)
     By default, no options are set for the standard locales, except
     for the "C" locale, which has OmitGroupSeparator set by default.
 
-    \sa setNumberOptions(), toString(), groupSeparator()
+    \sa setNumberOptions(), toString(), groupSeparator(), FloatingPointPrecisionOption
 */
 QLocale::NumberOptions QLocale::numberOptions() const
 {
@@ -2528,18 +2528,46 @@ static char qToLower(char c)
 
 /*!
     \overload
-
-    \a f and \a prec have the same meaning as in QString::number(double, char, int).
-
-    \sa toDouble(), numberOptions(), exponential(), decimalPoint(), zeroDigit(), positiveSign(), percent()
+    Returns a string representing the floating-point number \a f.
+
+    The form of the representation is controlled by the \a format and \a
+    precision parameters.
+
+    The \a format defaults to \c{'g'}. It can be any of the following:
+
+    \table
+    \header \li Format \li Meaning
+    \row \li \c 'e' \li format as [-]9.9e[+|-]999
+    \row \li \c 'E' \li format as [-]9.9E[+|-]999
+    \row \li \c 'f' \li format as [-]9.9
+    \row \li \c 'g' \li use \c 'e' or \c 'f' format, whichever is more concise
+    \row \li \c 'G' \li use \c 'E' or \c 'f' format, whichever is more concise
+    \endtable
+
+    For the \c 'e', \c 'E', and \c 'f' formats, the \a precision represents the
+    number of digits \e after the decimal point. For the \c 'g' and \c 'G'
+    formats, the \a precision represents the maximum number of significant
+    digits (trailing zeroes are omitted). The special \a precision value
+    QLocale::FloatingPointShortest selects the shortest representation that,
+    when read as a number, gets back the original floating-point value. Aside
+    from that, any negative \a precision is ignored in favor of the default, 6.
+
+    For the \c 'e', \c 'f' and \c 'g' formats, positive infinity is represented
+    as "inf", negative infinity as "-inf" and floating-point NaN (not-a-number)
+    values are represented as "nan". For the \c 'E' and \c 'G' formats, "INF"
+    and "NAN" are used instead. This does not vary with locale.
+
+    \sa toDouble(), numberOptions(), exponential(), decimalPoint(), zeroDigit(),
+        positiveSign(), percent(), toCurrencyString(), formattedDataSize(),
+        QLocale::FloatingPointPrecisionOption
 */
 
-QString QLocale::toString(double i, char f, int prec) const
+QString QLocale::toString(double f, char format, int precision) const
 {
     QLocaleData::DoubleForm form = QLocaleData::DFDecimal;
-    uint flags = qIsUpper(f) ? QLocaleData::CapitalEorX : 0;
+    uint flags = qIsUpper(format) ? QLocaleData::CapitalEorX : 0;
 
-    switch (qToLower(f)) {
+    switch (qToLower(format)) {
         case 'f':
             form = QLocaleData::DFDecimal;
             break;
@@ -2559,7 +2587,7 @@ QString QLocale::toString(double i, char f, int prec) const
         flags |= QLocaleData::ZeroPadExponent;
     if (d->m_numberOptions & IncludeTrailingZeroesAfterDot)
         flags |= QLocaleData::AddTrailingZeroes;
-    return d->m_data->doubleToString(i, prec, form, -1, flags);
+    return d->m_data->doubleToString(f, precision, form, -1, flags);
 }
 
 /*!
@@ -3374,8 +3402,11 @@ QString QCalendarBackend::dateTimeToString(QStringView format, const QDateTime &
 QString QLocaleData::doubleToString(double d, int precision, DoubleForm form,
                                     int width, unsigned flags) const
 {
-    // Undocumented: aside from F.P.Shortest, precision < 0 is treated as
-    // default, 6 - same as printf().
+    // Although the special handling of F.P.Shortest below is limited to
+    // DFSignificantDigits, the double-conversion library does treat it
+    // specially for the other forms, shedding trailing zeros for DFDecimal and
+    // using the shortest mantissa that faithfully represents the value for
+    // DFExponent.
     if (precision != QLocale::FloatingPointShortest && precision < 0)
         precision = 6;
     if (width < 0)
@@ -3387,8 +3418,8 @@ QString QLocaleData::doubleToString(double d, int precision, DoubleForm form,
         bufSize += std::numeric_limits<double>::max_digits10;
     else if (form == DFDecimal && qIsFinite(d))
         bufSize += wholePartSpace(qAbs(d)) + precision;
-    else // Add extra digit due to different interpretations of precision. Also, "nan" has to fit.
-        bufSize += qMax(2, precision) + 1;
+    else // Add extra digit due to different interpretations of precision.
+        bufSize += qMax(2, precision) + 1; // Must also be big enough for "nan" or "inf"
 
     QVarLengthArray<char> buf(bufSize);
     int length;
diff --git a/src/corelib/text/qlocale.h b/src/corelib/text/qlocale.h
index 77b3907b42..7611fc6efa 100644
--- a/src/corelib/text/qlocale.h
+++ b/src/corelib/text/qlocale.h
@@ -994,9 +994,9 @@ public:
     QString toString(ushort i) const { return toString(qulonglong(i)); }
     QString toString(int i) const { return toString(qlonglong(i)); }
     QString toString(uint i) const { return toString(qulonglong(i)); }
-    QString toString(double i, char f = 'g', int prec = 6) const;
-    QString toString(float i, char f = 'g', int prec = 6) const
-    { return toString(double(i), f, prec); }
+    QString toString(double f, char format = 'g', int precision = 6) const;
+    QString toString(float f, char format = 'g', int precision = 6) const
+    { return toString(double(f), format, precision); }
 
 #if QT_STRINGVIEW_LEVEL < 2
     // (Can't inline first two: passing by value doesn't work when only forward-declared.)
diff --git a/src/corelib/text/qlocale.qdoc b/src/corelib/text/qlocale.qdoc
index 9340ff2d59..529c8449be 100644
--- a/src/corelib/text/qlocale.qdoc
+++ b/src/corelib/text/qlocale.qdoc
@@ -995,23 +995,23 @@
             dot when parsing a number in scientific or decimal representation. The
             default is to accept trailing zeroes.
 
-    \sa setNumberOptions(), numberOptions()
+    \sa setNumberOptions(), numberOptions(), FloatingPointPrecisionOption
 */
 
 /*!
     \enum QLocale::FloatingPointPrecisionOption
 
-    This enum defines constants that can be given as precision to QString::number(),
+    This enum defines a constant that can be given as precision to QString::number(),
     QByteArray::number(), and QLocale::toString() when converting floats or doubles,
     in order to express a variable number of digits as precision.
 
     \value FloatingPointShortest The conversion algorithm will try to find the
-            shortest accurate representation for the given number. "Accurate" means
-            that you get the exact same number back from an inverse conversion on
-            the generated string representation.
-
-    \sa toString(), QString, QByteArray
+           shortest accurate representation for the given number. "Accurate" means
+           that you get the exact same number back from an inverse conversion on
+           the generated string representation. In particular, trailing zeros are
+           omitted (from the mantissa, in exponent formats).
 
+    \sa toString(), QString::number(), QByteArray::number()
     \since 5.7
 */
 
@@ -1256,13 +1256,17 @@
 */
 
 /*!
-\fn QString QLocale::toString(float i, char f = 'g', int prec = 6) const
-
+\fn QString QLocale::toString(float f, char format = 'g', int precision = 6) const
 \overload
 
-\a f and \a prec have the same meaning as in QString::number(double, char, int).
+Returns a string representing the floating-point number \a f.
+
+The \a format and \a precision have the same meanings as described in \l
+{toString(double, char, int)}.
 
-\sa toDouble()
+\sa toFloat(), toDouble(), numberOptions(), exponential(), decimalPoint(), zeroDigit(),
+    positiveSign(), percent(), toCurrencyString(), formattedDataSize(),
+    QLocale::FloatingPointPrecisionOption
 */
 
 /*!
diff --git a/src/corelib/text/qstring.cpp b/src/corelib/text/qstring.cpp
index 8d510dda6c..cb4a4b338c 100644
--- a/src/corelib/text/qstring.cpp
+++ b/src/corelib/text/qstring.cpp
@@ -1846,26 +1846,33 @@ inline char qToLower(char ch)
     (\e not nullptr) to a '\\0' character for a null string. We
     recommend that you always use the isEmpty() function and avoid isNull().
 
-    \section1 Argument Formats
-
-    In member functions where an argument \e format can be specified
-    (e.g., arg(), number()), the argument \e format can be one of the
-    following:
-
-    \table
-    \header \li Format \li Meaning
-    \row \li \c e \li format as [-]9.9e[+|-]999
-    \row \li \c E \li format as [-]9.9E[+|-]999
-    \row \li \c f \li format as [-]9.9
-    \row \li \c g \li use \c e or \c f format, whichever is the most concise
-    \row \li \c G \li use \c E or \c f format, whichever is the most concise
-    \endtable
-
-    A \e precision is also specified with the argument \e format. For
-    the 'e', 'E', and 'f' formats, the \e precision represents the
-    number of digits \e after the decimal point. For the 'g' and 'G'
-    formats, the \e precision represents the maximum number of
-    significant digits (trailing zeroes are omitted).
+    \section1 Number Formats
+
+    When a QString::arg() \c{'%'} format specifier includes the \c{'L'} locale
+    qualifier, and the base is ten (its default), the default locale is
+    used. This can be set using \l{QLocale::setDefault()}. For more refined
+    control of localized string representations of numbers, see
+    QLocale::toString(). All other number formatting done by QString follows the
+    C locale's representation of numbers.
+
+    When QString::arg() applies left-padding to numbers, the fill character
+    \c{'0'} is treated specially. If the number is negative, its minus sign will
+    appear before the zero-padding. If the field is localized, the
+    locale-appropriate zero character is used in place of \c{'0'}. For
+    floating-point numbers, this special treatment only applies if the number is
+    finite.
+
+    \section2 Floating-point Formats
+
+    In member functions (e.g., arg(), number()) that represent floating-point
+    numbers (\c float or \c double) as strings, the form of display can be
+    controlled by a choice of \e format and \e precision, whose meanings are as
+    for \l {QLocale::toString(double, char, int)}.
+
+    If the selected \e format includes an exponent, localized forms follow the
+    locale's convention on digits in the exponent. For non-localized formatting,
+    the exponent shows its sign and includes at least two digits, left-padding
+    with zero if needed.
 
     \section1 More Efficient String Construction
 
@@ -7226,26 +7233,17 @@ QString &QString::setNum(qulonglong n, int base)
 */
 
 /*!
-    \fn QString &QString::setNum(double n, char format, int precision)
     \overload
 
-    Sets the string to the printed value of \a n, formatted according
-    to the given \a format and \a precision, and returns a reference
-    to the string.
-
-    The \a format can be 'e', 'E', 'f', 'g' or 'G' (see
-    \l{Argument Formats} for an explanation of the formats).
-
-    The formatting always uses QLocale::C, i.e., English/UnitedStates.
-    To get a localized string representation of a number, use
-    QLocale::toString() with the appropriate locale.
+    Sets the string to the printed value of \a n, formatted according to the
+    given \a format and \a precision, and returns a reference to the string.
 
-    \sa number()
+    \sa number(), QLocale::FloatingPointPrecisionOption, {Number Formats}
 */
 
-QString &QString::setNum(double n, char f, int prec)
+QString &QString::setNum(double n, char format, int precision)
 {
-    return *this = number(n, f, prec);
+    return *this = number(n, format, precision);
 }
 
 /*!
@@ -7353,26 +7351,25 @@ QString QString::number(qulonglong n, int base)
 
 
 /*!
-    \fn QString QString::number(double n, char format, int precision)
+    Returns a string representing the floating-point number \a n.
 
-    Returns a string equivalent of the number \a n, formatted
-    according to the specified \a format and \a precision. See
-    \l{Argument Formats} for details.
+    Returns a string that represents \a n, formatted according to the specified
+    \a format and \a precision.
 
-    Unlike QLocale::toString(), this function does not honor the
-    user's locale settings.
+    For formats with an exponent, the exponent will show its sign and have at
+    least two digits, left-padding the exponent with zero if needed.
 
-    \sa setNum(), QLocale::toString()
+    \sa setNum(), QLocale::toString(), QLocale::FloatingPointPrecisionOption, {Number Formats}
 */
-QString QString::number(double n, char f, int prec)
+QString QString::number(double n, char format, int precision)
 {
     QLocaleData::DoubleForm form = QLocaleData::DFDecimal;
     uint flags = QLocaleData::ZeroPadExponent;
 
-    if (qIsUpper(f))
+    if (qIsUpper(format))
         flags |= QLocaleData::CapitalEorX;
 
-    switch (qToLower(f)) {
+    switch (qToLower(format)) {
         case 'f':
             form = QLocaleData::DFDecimal;
             break;
@@ -7384,12 +7381,12 @@ QString QString::number(double n, char f, int prec)
             break;
         default:
 #if defined(QT_CHECK_RANGE)
-            qWarning("QString::setNum: Invalid format char '%c'", f);
+            qWarning("QString::setNum: Invalid format char '%c'", format);
 #endif
             break;
     }
 
-    return QLocaleData::c()->doubleToString(n, prec, form, -1, flags);
+    return QLocaleData::c()->doubleToString(n, precision, form, -1, flags);
 }
 
 namespace {
@@ -7986,15 +7983,13 @@ QString QString::arg(QLatin1String a, int fieldWidth, QChar fillChar) const
   The '%' can be followed by an 'L', in which case the sequence is
   replaced with a localized representation of \a a. The conversion
   uses the default locale, set by QLocale::setDefault(). If no default
-  locale was specified, the "C" locale is used. The 'L' flag is
+  locale was specified, the system locale is used. The 'L' flag is
   ignored if \a base is not 10.
 
   \snippet qstring/main.cpp 12
   \snippet qstring/main.cpp 14
 
-  If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
-  used. For negative numbers, zero padding might appear before the
-  minus sign.
+  \sa {Number Formats}
 */
 
 /*! \fn QString QString::arg(uint a, int fieldWidth, int base, QChar fillChar) const
@@ -8003,9 +7998,7 @@ QString QString::arg(QLatin1String a, int fieldWidth, QChar fillChar) const
   The \a base argument specifies the base to use when converting the
   integer \a a into a string. The base must be between 2 and 36.
 
-  If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
-  used. For negative numbers, zero padding might appear before the
-  minus sign.
+  \sa {Number Formats}
 */
 
 /*! \fn QString QString::arg(long a, int fieldWidth, int base, QChar fillChar) const
@@ -8029,12 +8022,11 @@ QString QString::arg(QLatin1String a, int fieldWidth, QChar fillChar) const
   \snippet qstring/main.cpp 12
   \snippet qstring/main.cpp 14
 
-  If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
-  used. For negative numbers, zero padding might appear before the
-  minus sign.
+  \sa {Number Formats}
 */
 
-/*! \fn QString QString::arg(ulong a, int fieldWidth, int base, QChar fillChar) const
+/*!
+  \fn QString QString::arg(ulong a, int fieldWidth, int base, QChar fillChar) const
   \overload arg()
 
   \a fieldWidth specifies the minimum amount of space that \a a is
@@ -8046,9 +8038,7 @@ QString QString::arg(QLatin1String a, int fieldWidth, QChar fillChar) const
   integer \a a to a string. The base must be between 2 and 36, with 8
   giving octal, 10 decimal, and 16 hexadecimal numbers.
 
-  If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
-  used. For negative numbers, zero padding might appear before the
-  minus sign.
+  \sa {Number Formats}
 */
 
 /*!
@@ -8063,9 +8053,7 @@ QString QString::arg(QLatin1String a, int fieldWidth, QChar fillChar) const
   integer \a a into a string. The base must be between 2 and 36, with
   8 giving octal, 10 decimal, and 16 hexadecimal numbers.
 
-  If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
-  used. For negative numbers, zero padding might appear before the
-  minus sign.
+  \sa {Number Formats}
 */
 QString QString::arg(qlonglong a, int fieldWidth, int base, QChar fillChar) const
 {
@@ -8107,9 +8095,7 @@ QString QString::arg(qlonglong a, int fieldWidth, int base, QChar fillChar) cons
   integer \a a into a string. \a base must be between 2 and 36, with 8
   giving octal, 10 decimal, and 16 hexadecimal numbers.
 
-  If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
-  used. For negative numbers, zero padding might appear before the
-  minus sign.
+  \sa {Number Formats}
 */
 QString QString::arg(qulonglong a, int fieldWidth, int base, QChar fillChar) const
 {
@@ -8153,9 +8139,7 @@ QString QString::arg(qulonglong a, int fieldWidth, int base, QChar fillChar) con
   integer \a a into a string. The base must be between 2 and 36, with
   8 giving octal, 10 decimal, and 16 hexadecimal numbers.
 
-  If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
-  used. For negative numbers, zero padding might appear before the
-  minus sign.
+  \sa {Number Formats}
 */
 
 /*!
@@ -8171,9 +8155,7 @@ QString QString::arg(qulonglong a, int fieldWidth, int base, QChar fillChar) con
   integer \a a into a string. The base must be between 2 and 36, with
   8 giving octal, 10 decimal, and 16 hexadecimal numbers.
 
-  If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
-  used. For negative numbers, zero padding might appear before the
-  minus sign.
+  \sa {Number Formats}
 */
 
 /*!
@@ -8195,11 +8177,10 @@ QString QString::arg(char a, int fieldWidth, QChar fillChar) const
 }
 
 /*!
-  \fn QString QString::arg(double a, int fieldWidth, char format, int precision, QChar fillChar) const
   \overload arg()
 
   Argument \a a is formatted according to the specified \a format and
-  \a precision. See \l{Argument Formats} for details.
+  \a precision. See \l{Floating-point Formats} for details.
 
   \a fieldWidth specifies the minimum amount of space that \a a is
   padded to and filled with the character \a fillChar.  A positive
@@ -8208,18 +8189,9 @@ QString QString::arg(char a, int fieldWidth, QChar fillChar) const
 
   \snippet code/src_corelib_text_qstring.cpp 2
 
-  The '%' can be followed by an 'L', in which case the sequence is
-  replaced with a localized representation of \a a. The conversion
-  uses the default locale, set by QLocale::setDefault(). If no
-  default locale was specified, the "C" locale is used.
-
-  If \a fillChar is '0' (the number 0, ASCII 48), this function will
-  use the locale's zero to pad. For negative numbers, the zero padding
-  will probably appear before the minus sign.
-
-  \sa QLocale::toString()
+  \sa QLocale::toString(), QLocale::FloatingPointPrecisionOption, {Number Formats}
 */
-QString QString::arg(double a, int fieldWidth, char fmt, int prec, QChar fillChar) const
+QString QString::arg(double a, int fieldWidth, char format, int precision, QChar fillChar) const
 {
     ArgEscapeData d = findArgEscapes(*this);
 
@@ -8232,11 +8204,11 @@ QString QString::arg(double a, int fieldWidth, char fmt, int prec, QChar fillCha
     if (fillChar == QLatin1Char('0'))
         flags |= QLocaleData::ZeroPadded;
 
-    if (qIsUpper(fmt))
+    if (qIsUpper(format))
         flags |= QLocaleData::CapitalEorX;
 
     QLocaleData::DoubleForm form = QLocaleData::DFDecimal;
-    switch (qToLower(fmt)) {
+    switch (qToLower(format)) {
     case 'f':
         form = QLocaleData::DFDecimal;
         break;
@@ -8248,14 +8220,14 @@ QString QString::arg(double a, int fieldWidth, char fmt, int prec, QChar fillCha
         break;
     default:
 #if defined(QT_CHECK_RANGE)
-        qWarning("QString::arg: Invalid format char '%c'", fmt);
+        qWarning("QString::arg: Invalid format char '%c'", format);
 #endif
         break;
     }
 
     QString arg;
     if (d.occurrences > d.locale_occurrences)
-        arg = QLocaleData::c()->doubleToString(a, prec, form, fieldWidth, flags | QLocaleData::ZeroPadExponent);
+        arg = QLocaleData::c()->doubleToString(a, precision, form, fieldWidth, flags | QLocaleData::ZeroPadExponent);
 
     QString locale_arg;
     if (d.locale_occurrences > 0) {
@@ -8268,7 +8240,7 @@ QString QString::arg(double a, int fieldWidth, char fmt, int prec, QChar fillCha
             flags |= QLocaleData::ZeroPadExponent;
         if (numberOptions & QLocale::IncludeTrailingZeroesAfterDot)
             flags |= QLocaleData::AddTrailingZeroes;
-        locale_arg = locale.d->m_data->doubleToString(a, prec, form, fieldWidth, flags);
+        locale_arg = locale.d->m_data->doubleToString(a, precision, form, fieldWidth, flags);
     }
 
     return replaceArgEscapes(*this, d, fieldWidth, arg, locale_arg, fillChar);
diff --git a/src/corelib/text/qstring.h b/src/corelib/text/qstring.h
index cce57cd578..75ba485998 100644
--- a/src/corelib/text/qstring.h
+++ b/src/corelib/text/qstring.h
@@ -464,7 +464,7 @@ public:
                 QChar fillChar = QLatin1Char(' ')) const;
     [[nodiscard]] QString arg(ushort a, int fieldWidth = 0, int base = 10,
                 QChar fillChar = QLatin1Char(' ')) const;
-    [[nodiscard]] QString arg(double a, int fieldWidth = 0, char fmt = 'g', int prec = -1,
+    [[nodiscard]] QString arg(double a, int fieldWidth = 0, char format = 'g', int precision = -1,
                 QChar fillChar = QLatin1Char(' ')) const;
     [[nodiscard]] QString arg(char a, int fieldWidth = 0,
                 QChar fillChar = QLatin1Char(' ')) const;
@@ -854,8 +854,8 @@ public:
     QString &setNum(ulong, int base=10);
     QString &setNum(qlonglong, int base=10);
     QString &setNum(qulonglong, int base=10);
-    QString &setNum(float, char f='g', int prec=6);
-    QString &setNum(double, char f='g', int prec=6);
+    QString &setNum(float, char format='g', int precision=6);
+    QString &setNum(double, char format='g', int precision=6);
 
     static QString number(int, int base=10);
     static QString number(uint, int base=10);
@@ -863,7 +863,7 @@ public:
     static QString number(ulong, int base=10);
     static QString number(qlonglong, int base=10);
     static QString number(qulonglong, int base=10);
-    static QString number(double, char f='g', int prec=6);
+    static QString number(double, char format='g', int precision=6);
 
     friend bool operator==(const QString &s1, const QString &s2) noexcept
     { return (s1.size() == s2.size()) && QtPrivate::compareStrings(s1, s2, Qt::CaseSensitive) == 0; }