qdoc: Fix remaining qdoc warnings for QCborxxx classes

Several \fn commands are added for functions and operators that
were not documented. A few qdoc warnings remain in qcborstream.cpp,
but these are because an enum class was used, and qdoc doesn't yet
handle those correctly all the time.

Change-Id: I02a740c595e36c1b383af242c2a6419d1f37b135
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

5 files changed, 121 insertions, 6 deletions

diff --git a/src/corelib/serialization/qcborarray.cpp b/src/corelib/serialization/qcborarray.cpp
index 28ee941a15..506fb052be 100644
--- a/src/corelib/serialization/qcborarray.cpp
+++ b/src/corelib/serialization/qcborarray.cpp
@@ -327,8 +327,8 @@ void QCborArray::insert(qsizetype i, QCborValue &&value)
 }
 
 /*!
-    \fn QCborValue QCborArray::extract(iterator it)
-    \fn QCborValue QCborArray::extract(const_iterator it)
+    \fn QCborValue QCborArray::extract(Iterator it)
+    \fn QCborValue QCborArray::extract(ConstIterator it)
 
     Extracts a value from the array at the position indicated by iterator \a it
     and returns the value so extracted.
@@ -1048,6 +1048,7 @@ void QCborArray::detach(qsizetype reserved)
 */
 
 /*!
+    \fn bool QCborArray::ConstIterator::operator==(const Iterator &other) const
     \fn bool QCborArray::ConstIterator::operator==(const ConstIterator &other) const
 
     Returns \c true if \a other points to the same entry in the array as this
@@ -1067,6 +1068,7 @@ void QCborArray::detach(qsizetype reserved)
 */
 
 /*!
+    \fn bool QCborArray::ConstIterator::operator<(const Iterator &other) const
     \fn bool QCborArray::ConstIterator::operator<(const ConstIterator &other) const
 
     Returns \c true if the entry in the array pointed to by this iterator
@@ -1074,6 +1076,7 @@ void QCborArray::detach(qsizetype reserved)
 */
 
 /*!
+    \fn bool QCborArray::ConstIterator::operator<=(const Iterator &other) const
     \fn bool QCborArray::ConstIterator::operator<=(const ConstIterator &other) const
 
     Returns \c true if the entry in the array pointed to by this iterator
@@ -1082,6 +1085,7 @@ void QCborArray::detach(qsizetype reserved)
 */
 
 /*!
+    \fn bool QCborArray::ConstIterator::operator>(const Iterator &other) const
     \fn bool QCborArray::ConstIterator::operator>(const ConstIterator &other) const
 
     Returns \c true if the entry in the array pointed to by this iterator
@@ -1089,6 +1093,7 @@ void QCborArray::detach(qsizetype reserved)
 */
 
 /*!
+    \fn bool QCborArray::ConstIterator::operator>=(const Iterator &other) const
     \fn bool QCborArray::ConstIterator::operator>=(const ConstIterator &other) const
 
     Returns \c true if the entry in the array pointed to by this iterator
diff --git a/src/corelib/serialization/qcbordiagnostic.cpp b/src/corelib/serialization/qcbordiagnostic.cpp
index 78f99927c8..75feaded17 100644
--- a/src/corelib/serialization/qcbordiagnostic.cpp
+++ b/src/corelib/serialization/qcbordiagnostic.cpp
@@ -337,7 +337,7 @@ void DiagnosticNotation::appendValue(const QCborValue &v)
     high-fidelity notation of a stream, without transformation, see the \c
     cbordump example.
 
-    \sa toCbor(), toJsonDocument(), QJsonDocument::toJson()
+    \sa toCbor(), QJsonDocument::toJson()
  */
 QString QCborValue::toDiagnosticNotation(DiagnosticNotationOptions opts) const
 {
diff --git a/src/corelib/serialization/qcbormap.cpp b/src/corelib/serialization/qcbormap.cpp
index b7067f4afd..f9b000393c 100644
--- a/src/corelib/serialization/qcbormap.cpp
+++ b/src/corelib/serialization/qcbormap.cpp
@@ -804,6 +804,9 @@ QCborValueRef QCborMap::operator[](const QCborValue &key)
 }
 
 /*!
+    \fn QCborMap::iterator QCborMap::find(qint64 key)
+    \fn QCborMap::const_iterator QCborMap::find(qint64 key) const
+
     Returns a map iterator to the key-value pair whose key is \a key, if the
     map contains such a pair. If it doesn't, this function returns end().
 
@@ -828,6 +831,8 @@ QCborMap::iterator QCborMap::find(qint64 key)
 }
 
 /*!
+    \fn QCborMap::iterator QCborMap::find(QLatin1String key)
+    \fn QCborMap::const_iterator QCborMap::find(QLatin1String key) const
     \overload
 
     Returns a map iterator to the key-value pair whose key is \a key, if the
@@ -852,6 +857,8 @@ QCborMap::iterator QCborMap::find(QLatin1String key)
 }
 
 /*!
+    \fn QCborMap::iterator QCborMap::find(const QString & key)
+    \fn QCborMap::const_iterator QCborMap::find(const QString & key) const
     \overload
 
     Returns a map iterator to the key-value pair whose key is \a key, if the
@@ -876,6 +883,8 @@ QCborMap::iterator QCborMap::find(const QString & key)
 }
 
 /*!
+    \fn QCborMap::iterator QCborMap::find(const QCborValue &key)
+    \fn QCborMap::const_iterator QCborMap::find(const QCborValue &key) const
     \overload
 
     Returns a map iterator to the key-value pair whose key is \a key, if the
@@ -1100,6 +1109,9 @@ QCborMap::iterator QCborMap::erase(QCborMap::iterator it)
 }
 
 /*!
+    \fn QCborValue QCborMap::extract(iterator it)
+    \fn QCborValue QCborMap::extract(const_iterator it)
+
     Extracts a value from the map at the position indicated by iterator \a it
     and returns the value so extracted.
 
@@ -1360,6 +1372,40 @@ void QCborMap::detach(qsizetype reserved)
 */
 
 /*!
+    \fn bool QCborMap::Iterator::operator<(const Iterator& other) const
+    \fn bool QCborMap::Iterator::operator<(const ConstIterator& other) const
+
+    Returns \c true if the entry in the map pointed to by this iterator
+    occurs before the entry pointed to by the \a other iterator.
+*/
+
+/*!
+    \fn bool QCborMap::Iterator::operator<=(const Iterator& other) const
+    \fn bool QCborMap::Iterator::operator<=(const ConstIterator& other) const
+
+    Returns \c true if the entry in the map pointed to by this iterator
+    occurs before or is the same entry as is pointed to by the \a other
+    iterator.
+*/
+
+/*!
+    \fn bool QCborMap::Iterator::operator>(const Iterator& other) const
+    \fn bool QCborMap::Iterator::operator>(const ConstIterator& other) const
+
+    Returns \c true if the entry in the map pointed to by this iterator
+    occurs after the entry pointed to by the \a other iterator.
+ */
+
+/*!
+    \fn bool QCborMap::Iterator::operator>=(const Iterator& other) const
+    \fn bool QCborMap::Iterator::operator>=(const ConstIterator& other) const
+
+    Returns \c true if the entry in the map pointed to by this iterator
+    occurs after or is the same entry as is pointed to by the \a other
+    iterator.
+*/
+
+/*!
     \fn QCborMap::Iterator &QCborMap::Iterator::operator++()
 
     The prefix ++ operator, \c{++i}, advances the iterator to the next item in
@@ -1416,6 +1462,16 @@ void QCborMap::detach(qsizetype reserved)
 */
 
 /*!
+    \fn qsizetype QCborMap::Iterator::operator-(QCborMap::Iterator j) const
+
+    Returns the position of the item at iterator \a j relative to the item
+    at this iterator. If the item at \a j is forward of this time, the returned
+    value is negative.
+
+    \sa operator+()
+*/
+
+/*!
     \fn QCborMap::Iterator &QCborMap::Iterator::operator+=(qsizetype j)
 
     Advances the iterator by \a j items. If \a j is negative, the iterator goes
@@ -1561,6 +1617,40 @@ void QCborMap::detach(qsizetype reserved)
  */
 
 /*!
+    \fn bool QCborMap::ConstIterator::operator<(const Iterator &other) const
+    \fn bool QCborMap::ConstIterator::operator<(const ConstIterator &other) const
+
+    Returns \c true if the entry in the map pointed to by this iterator
+    occurs before the entry pointed to by the \a other iterator.
+*/
+
+/*!
+    \fn bool QCborMap::ConstIterator::operator<=(const Iterator &other) const
+    \fn bool QCborMap::ConstIterator::operator<=(const ConstIterator &other) const
+
+    Returns \c true if the entry in the map pointed to by this iterator
+    occurs before or is the same entry as is pointed to by the \a other
+    iterator.
+*/
+
+/*!
+    \fn bool QCborMap::ConstIterator::operator>(const Iterator &other) const
+    \fn bool QCborMap::ConstIterator::operator>(const ConstIterator &other) const
+
+    Returns \c true if the entry in the map pointed to by this iterator
+    occurs after the entry pointed to by the \a other iterator.
+*/
+
+/*!
+    \fn bool QCborMap::ConstIterator::operator>=(const Iterator &other) const
+    \fn bool QCborMap::ConstIterator::operator>=(const ConstIterator &other) const
+
+    Returns \c true if the entry in the map pointed to by this iterator
+    occurs after or is the same entry as is pointed to by the \a other
+    iterator.
+*/
+
+/*!
     \fn QCborMap::ConstIterator &QCborMap::ConstIterator::operator++()
 
     The prefix ++ operator, \c{++i}, advances the iterator to the next item in
@@ -1617,6 +1707,16 @@ void QCborMap::detach(qsizetype reserved)
 */
 
 /*!
+    \fn qsizetype QCborMap::ConstIterator::operator-(QCborMap::ConstIterator j) const
+
+    Returns the position of the item at iterator \a j relative to the item
+    at this iterator. If the item at \a j is forward of this time, the returned
+    value is negative.
+
+    \sa operator+()
+*/
+
+/*!
     \fn QCborMap::ConstIterator &QCborMap::ConstIterator::operator+=(qsizetype j)
 
     Advances the iterator by \a j items. If \a j is negative, the iterator goes
diff --git a/src/corelib/serialization/qcborstream.cpp b/src/corelib/serialization/qcborstream.cpp
index ce1b981f8f..aed286a11f 100644
--- a/src/corelib/serialization/qcborstream.cpp
+++ b/src/corelib/serialization/qcborstream.cpp
@@ -1044,7 +1044,7 @@ void QCborStreamWriter::append(QCborSimpleType st)
 
    Appends the floating point number \a f to the stream, creating a CBOR 16-bit
    Half-Precision Floating Point value. The following code can be used to convert
-   a C++ \tt float to \l qfloat16 if there's no loss of precision and append it, or
+   a C++ \tt float to \c qfloat16 if there's no loss of precision and append it, or
    instead append the \tt float.
 
    \code
@@ -1144,7 +1144,7 @@ void QCborStreamWriter::append(double d)
    QCborStreamReader::readByteArray() nor QCborValue support reading CBOR
    streams with byte arrays larger than 2 GB.
 
-   \sa append(QByteArray), appendTextString(),
+   \sa append(), appendTextString(),
        QCborStreamReader::isByteArray(), QCborStreamReader::readByteArray()
  */
 void QCborStreamWriter::appendByteString(const char *data, qsizetype len)
diff --git a/src/corelib/serialization/qcborvalue.cpp b/src/corelib/serialization/qcborvalue.cpp
index 4108418550..c1d78ef738 100644
--- a/src/corelib/serialization/qcborvalue.cpp
+++ b/src/corelib/serialization/qcborvalue.cpp
@@ -2197,6 +2197,16 @@ QCborValue QCborValue::fromCbor(const QByteArray &ba, QCborParserError *error)
 }
 
 /*!
+    \fn QCborValue QCborValue::fromCbor(const char *data, qsizetype len, QCborParserError *error)
+    \fn QCborValue QCborValue::fromCbor(const quint8 *data, qsizetype len, QCborParserError *error)
+    \overload
+
+    Converts \a len bytes of \a data to a QByteArray and then calls the
+    overload of this function that accepts a QByteArray, also passing \a error,
+    if provided.
+*/
+
+/*!
     Encodes this QCborValue object to its CBOR representation, using the
     options specified in \a opt, and return the byte array containing that
     representation.
@@ -2213,7 +2223,7 @@ QCborValue QCborValue::fromCbor(const QByteArray &ba, QCborParserError *error)
     infinities and NaN values.
 
     Similarly, if \l{EncodingOption}{UseFloat16} is specified, this function
-    will try to use half-precision (\l qfloat16) floating point if the
+    will try to use half-precision (\c qfloat16) floating point if the
     conversion to that results in no loss of precision. This is always true for
     infinities and NaN.