From ecd86b1894845d3d527fadacac1b90e562b3ed5e Mon Sep 17 00:00:00 2001 From: Topi Reinio Date: Thu, 29 Oct 2020 17:57:24 +0100 Subject: Doc: Fix documentation warnings for string classes Task-number: QTBUG-86295 Change-Id: I13033635eecd495b32c98c7ec9318a0102b6f23e Reviewed-by: Paul Wicking --- src/corelib/text/qanystringview.qdoc | 48 ++++++++--------------------- src/corelib/text/qstring.h | 2 +- src/corelib/text/qstringconverter.cpp | 57 +++++++++-------------------------- src/corelib/text/qstringview.cpp | 15 ++++++++- 4 files changed, 42 insertions(+), 80 deletions(-) (limited to 'src/corelib') diff --git a/src/corelib/text/qanystringview.qdoc b/src/corelib/text/qanystringview.qdoc index 096eea821c..baec2f89b5 100644 --- a/src/corelib/text/qanystringview.qdoc +++ b/src/corelib/text/qanystringview.qdoc @@ -231,23 +231,6 @@ The string view will be null if and only if \c{str.isNull()}. */ -/*! - \fn template QAnyStringView::QAnyStringView(const StdBasicString &str) - - Constructs a string view on \a str. The length is taken from \c{str.size()}. - - \c{str.data()} must remain valid for the lifetime of this string view object. - - This constructor only participates in overload resolution if \c StdBasicString is an - instantiation of \c std::basic_string with a compatible character type. - - The string view will be empty if and only if \c{str.empty()}. It is unspecified - whether this constructor can result in a null string view (\c{str.data()} would - have to return \nullptr for this). - - \sa isNull(), isEmpty(), {Compatible Character Types} -*/ - /*! \fn template static QAnyStringView fromArray(const Char (&string)[Size]) noexcept @@ -390,6 +373,19 @@ \sa operator==(), operator<(), operator>() */ +/*! + \fn QAnyStringView::operator==(QAnyStringView lhs, QAnyStringView rhs) + \fn QAnyStringView::operator!=(QAnyStringView lhs, QAnyStringView rhs) + \fn QAnyStringView::operator<=(QAnyStringView lhs, QAnyStringView rhs) + \fn QAnyStringView::operator>=(QAnyStringView lhs, QAnyStringView rhs) + \fn QAnyStringView::operator<(QAnyStringView lhs, QAnyStringView rhs) + \fn QAnyStringView::operator>(QAnyStringView lhs, QAnyStringView rhs) + + Operators that compare \a lhs to \a rhs. + + \sa compare() +*/ + /*! \fn template qToAnyStringViewIgnoringNull(const QStringLike &s); \since 6.0 @@ -405,21 +401,3 @@ \sa QString::isNull(), QAnyStringView */ -/*! - \fn QAnyStringView::toWCharArray(wchar_t *array) const - - Transcribes this string into the given \a array. - - The caller is responsible for ensuring \a array is large enough to hold the - \c wchar_t encoding of this string (allocating the array with space for size() - elements is always sufficient). The array is encoded in UTF-16 on - platforms where \c wchar_t is 2 bytes wide (e.g. Windows); otherwise (Unix - systems), \c wchar_t is assumed to be 4 bytes wide and the data is written - in UCS-4. - - \note This function writes no null terminator to the end of \a array. - - Returns the number of \c wchar_t entries written to \a array. - - \sa QString::toWCharArray() -*/ diff --git a/src/corelib/text/qstring.h b/src/corelib/text/qstring.h index 653d135cd2..91edd77a17 100644 --- a/src/corelib/text/qstring.h +++ b/src/corelib/text/qstring.h @@ -739,7 +739,7 @@ public: { return fromUtf8(QByteArrayView(utf8, !utf8 || size < 0 ? qstrlen(utf8) : size)); } -#ifdef __cpp_char8_t +#if defined(__cpp_char8_t) || defined(Q_CLANG_QDOC) Q_WEAK_OVERLOAD static inline QString fromUtf8(const char8_t *str, qsizetype size) { return fromUtf8(reinterpret_cast(str), int(size)); } diff --git a/src/corelib/text/qstringconverter.cpp b/src/corelib/text/qstringconverter.cpp index c276d807ec..e8323745d2 100644 --- a/src/corelib/text/qstringconverter.cpp +++ b/src/corelib/text/qstringconverter.cpp @@ -1634,6 +1634,7 @@ static qsizetype toLatin1Len(qsizetype l) { return l + 1; } \value System Create a converter to or from the underlying encoding of the operating systems locale. This is always assumed to be UTF-8 for Unix based systems. On Windows, this converts to and from the locale code page. + \omitvalue LastEncoding */ /*! @@ -1838,7 +1839,7 @@ std::optional QStringConverter::encodingForHtml(QByt } /*! - Returns the canonical name for \a encoding. + Returns the canonical name for encoding \a e. */ const char *QStringConverter::nameForEncoding(QStringConverter::Encoding e) { @@ -1904,48 +1905,34 @@ const char *QStringConverter::nameForEncoding(QStringConverter::Encoding e) */ /*! - \fn QByteArray QStringEncoder::operator()(const QString &in) \fn QByteArray QStringEncoder::encode(const QString &in) - - Converts \a in and returns the data as a byte array. -*/ - -/*! - \fn QByteArray QStringEncoder::operator()(QStringView in) \fn QByteArray QStringEncoder::encode(QStringView in) - \overload + \fn QByteArray QStringEncoder::operator()(const QString &in) + \fn QByteArray QStringEncoder::operator()(QStringView in) Converts \a in and returns the data as a byte array. */ -/*! - \fn QByteArray QStringEncoder::operator()(const QChar *in, qsizetype length) - \fn QByteArray QStringEncoder::encode(const QChar *in, qsizetype length) - \overload - - Converts \a length QChars from \a in and returns the data as a byte array. -*/ - /*! \fn qsizetype QStringEncoder::requiredSpace(qsizetype inputLength) const Returns the maximum amount of characters required to be able to process \a inputLength decoded data. - \sa appendToBuffer + \sa appendToBuffer() */ /*! - \fn char *QStringEncoder::appendToBuffer(char *out, const QChar *in, qsizetype length) + \fn char *QStringEncoder::appendToBuffer(char *out, QStringView in) - Encodes \a length QChars from \a in and writes the encoded result into the buffer - starting at \a out. Returns a pointer to the end of data written. + Encodes \a in and writes the encoded result into the buffer + starting at \a out. Returns a pointer to the end of the data written. - \a out needs to be large enough to be able to hold all the decoded data. Use - \l{requiredSpace} to determine the maximum size requirements to be able to encode - a QChar buffer of \a length. + \note \a out must be large enough to be able to hold all the decoded data. Use + requiredSpace() to determine the maximum size requirement to be able to encode + \a in. - \sa requiredSpace + \sa requiredSpace() */ /*! @@ -2009,28 +1996,12 @@ const char *QStringConverter::nameForEncoding(QStringConverter::Encoding e) /*! \fn QString QStringDecoder::operator()(const QByteArray &ba) \fn QString QStringDecoder::decode(const QByteArray &ba) + \fn QString QStringDecoder::operator()(QByteArrayView ba) + \fn QString QStringDecoder::decode(QByteArrayView ba) Converts \a ba and returns the data as a QString. */ -/*! - \fn QString QStringDecoder::operator()(const char *in, qsizetype size) - \fn QString QStringDecoder::decode(const char *in, qsizetype size) - \overload - - Converts a byte array containing the first \a size bytes of the array \a in - and returns the data as a QString. -*/ - -/*! - \fn QString QStringDecoder::operator()(const char *chars) - \fn QString QStringDecoder::decode(const char *chars) - \overload - - Converts \a chars and returns the data as a QString. \a chars is assumed to - point to a \c{\0}-terminated string and its length is determined dynamically. -*/ - /*! \fn qsizetype QStringDecoder::requiredSpace(qsizetype inputLength) const diff --git a/src/corelib/text/qstringview.cpp b/src/corelib/text/qstringview.cpp index ca9b6d1b7b..75952066b8 100644 --- a/src/corelib/text/qstringview.cpp +++ b/src/corelib/text/qstringview.cpp @@ -305,7 +305,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn template QStringView::QStringView(const StdBasicString &str) + \fn template > QStringView::QStringView(const Container &str) Constructs a string view on \a str. The length is taken from \c{str.size()}. @@ -784,6 +784,19 @@ QT_BEGIN_NAMESPACE \sa operator==(), operator<(), operator>() */ +/*! + \fn QStringView::operator==(QStringView lhs, QStringView rhs) + \fn QStringView::operator!=(QStringView lhs, QStringView rhs) + \fn QStringView::operator< (QStringView lhs, QStringView rhs) + \fn QStringView::operator<=(QStringView lhs, QStringView rhs) + \fn QStringView::operator> (QStringView lhs, QStringView rhs) + \fn QStringView::operator>=(QStringView lhs, QStringView rhs) + + Operators for comparing \a lhs to \a rhs. + + \sa compare() +*/ + /*! \fn bool QStringView::startsWith(QStringView str, Qt::CaseSensitivity cs) const \fn bool QStringView::startsWith(QLatin1String l1, Qt::CaseSensitivity cs) const -- cgit v1.2.3