Fixed most qdoc errors for the json classes.

Change-Id: Ibbbdd7212f6c5e25422bbaa9ccaf4822db52222a
Reviewed-by: Casper van Donderen <casper.vandonderen@nokia.com>
Reviewed-by: Richard J. Moore <rich@kde.org>

6 files changed, 221 insertions, 39 deletions

diff --git a/src/corelib/json/qjsonarray.cpp b/src/corelib/json/qjsonarray.cpp
index e1ed53a840..6c4cfe17ca 100644
--- a/src/corelib/json/qjsonarray.cpp
+++ b/src/corelib/json/qjsonarray.cpp
@@ -74,6 +74,60 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
+    \typedef QJsonArray::Iterator
+
+    Qt-style synonym for QJsonArray::iterator.
+*/
+
+/*!
+    \typedef QJsonArray::ConstIterator
+
+    Qt-style synonym for QJsonArray::const_iterator.
+*/
+
+/*!
+    \typedef QJsonArray::size_type
+
+    Typedef for int. Provided for STL compatibility.
+*/
+
+/*!
+    \typedef QJsonArray::value_type
+
+    Typedef for QJsonValue. Provided for STL compatibility.
+*/
+
+/*!
+    \typedef QJsonArray::difference_type
+
+    Typedef for int. Provided for STL compatibility.
+*/
+
+/*!
+    \typedef QJsonArray::pointer
+
+    Typedef for QJsonValue *. Provided for STL compatibility.
+*/
+
+/*!
+    \typedef QJsonArray::const_pointer
+
+    Typedef for const QJsonValue *. Provided for STL compatibility.
+*/
+
+/*!
+    \typedef QJsonArray::reference
+
+    Typedef for QJsonValue &. Provided for STL compatibility.
+*/
+
+/*!
+    \typedef QJsonArray::const_reference
+
+    Typedef for const QJsonValue &. Provided for STL compatibility.
+*/
+
+/*!
     Creates an empty array.
  */
 QJsonArray::QJsonArray()
@@ -137,7 +191,7 @@ QJsonArray &QJsonArray::operator =(const QJsonArray &other)
 
     The values in \a list will be converted to JSON values.
 
-    \sa toVariantList, QJsonValue::fromString
+    \sa toVariantList(), QJsonValue::fromVariant()
  */
 QJsonArray QJsonArray::fromStringList(const QStringList &list)
 {
@@ -152,7 +206,7 @@ QJsonArray QJsonArray::fromStringList(const QStringList &list)
 
     The QVariant values in \a list will be converted to JSON values.
 
-    \sa toVariantList, QJsonValue::fromVariant
+    \sa toVariantList(), QJsonValue::fromVariant()
  */
 QJsonArray QJsonArray::fromVariantList(const QVariantList &list)
 {
@@ -191,9 +245,17 @@ int QJsonArray::size() const
 }
 
 /*!
+    \fn QJsonArray::count() const
+
+    Same as size().
+
+    \sa size()
+*/
+
+/*!
     Returns \c true if the object is empty. This is the same as size() == 0.
 
-    \sa size
+    \sa size()
  */
 bool QJsonArray::isEmpty() const
 {
@@ -222,7 +284,7 @@ QJsonValue QJsonArray::at(int i) const
 
     Same as \c at(0).
 
-    \sa at
+    \sa at()
  */
 QJsonValue QJsonArray::first() const
 {
@@ -234,7 +296,7 @@ QJsonValue QJsonArray::first() const
 
     Same as \c{at(size() - 1)}.
 
-    \sa at
+    \sa at()
  */
 QJsonValue QJsonArray::last() const
 {
@@ -288,7 +350,7 @@ void QJsonArray::removeAt(int i)
     the array can be empty, call isEmpty() before calling this
     function.
 
-    \sa removeAt(), takeFirst()
+    \sa removeAt(), removeLast()
 */
 
 /*! \fn void QJsonArray::removeLast()
@@ -298,7 +360,7 @@ void QJsonArray::removeAt(int i)
     empty. If the array can be empty, call isEmpty() before calling
     this function.
 
-    \sa removeAt(), takeLast()
+    \sa removeAt(), removeFirst()
 */
 
 /*!
@@ -354,6 +416,24 @@ void QJsonArray::insert(int i, const QJsonValue &value)
 }
 
 /*!
+    \fn QJsonArray::iterator QJsonArray::insert(iterator before, const QJsonValue &value)
+
+    Inserts \a value before the position pointed to by \a before, and returns an iterator
+    pointing to the newly inserted item.
+
+    \sa erase(), insert()
+*/
+
+/*!
+    \fn QJsonArray::iterator QJsonArray::erase(iterator it)
+
+    Removes the item pointed to by \a it, and returns an iterator pointing to the
+    next item.
+
+    \sa removeAt()
+*/
+
+/*!
     Replaces the item at index position \a i with \a value. \a i must
     be a valid index position in the array (i.e., \c{0 <= \a i < size()}).
 
@@ -410,7 +490,7 @@ bool QJsonArray::contains(const QJsonValue &value) const
     the assignment will apply to the character in the QJsonArray of QJsonObject
     from which you got the reference.
 
-    \sa at(), value()
+    \sa at()
  */
 QJsonValueRef QJsonArray::operator [](int i)
 {
@@ -775,7 +855,7 @@ bool QJsonArray::operator!=(const QJsonArray &other) const
     aware that any non-const function call performed on the QJsonArray
     will render all existing iterators undefined.
 
-    \sa QJsonArray::iterator, QJsonArrayIterator
+    \sa QJsonArray::iterator
 */
 
 /*! \fn QJsonArray::const_iterator::const_iterator()
diff --git a/src/corelib/json/qjsonarray.h b/src/corelib/json/qjsonarray.h
index 83b07e33c9..2be55b6685 100644
--- a/src/corelib/json/qjsonarray.h
+++ b/src/corelib/json/qjsonarray.h
@@ -179,7 +179,7 @@ public:
     inline const_iterator end() const { return const_iterator(this, size()); }
     inline const_iterator constEnd() const { return const_iterator(this, size()); }
     iterator insert(iterator before, const QJsonValue &value) { insert(before.i, value); return before; }
-    iterator erase(iterator pos) { removeAt(pos.i); return pos; }
+    iterator erase(iterator it) { removeAt(it.i); return it; }
 
     // more Qt
     typedef iterator Iterator;
diff --git a/src/corelib/json/qjsondocument.cpp b/src/corelib/json/qjsondocument.cpp
index ae59847dc6..1d8142c56c 100644
--- a/src/corelib/json/qjsondocument.cpp
+++ b/src/corelib/json/qjsondocument.cpp
@@ -176,7 +176,7 @@ QJsonDocument &QJsonDocument::operator =(const QJsonDocument &other)
 
  Returns a QJsonDocument representing the data.
 
- \sa rawData, fromBinaryData, isNull, DataValidation
+ \sa rawData(), fromBinaryData(), isNull(), DataValidation
  */
 QJsonDocument QJsonDocument::fromRawData(const char *data, int size, DataValidation validation)
 {
@@ -198,7 +198,7 @@ QJsonDocument QJsonDocument::fromRawData(const char *data, int size, DataValidat
 
 /*!
   Returns the raw binary representation of the data
-  \a size will contain the size of the \a data.
+  \a size will contain the size of the returned data.
 
   This method is useful to e.g. stream the JSON document
   in it's binary form to a file.
@@ -220,7 +220,7 @@ const char *QJsonDocument::rawData(int *size) const
  By default the data is validated. If the \a data is not valid, the method returns
  a null document.
 
- \sa toBinaryData, fromRawData, isNull, DataValidation
+ \sa toBinaryData(), fromRawData(), isNull(), DataValidation
  */
 QJsonDocument QJsonDocument::fromBinaryData(const QByteArray &data, DataValidation validation)
 {
@@ -260,7 +260,7 @@ QJsonDocument QJsonDocument::fromBinaryData(const QByteArray &data, DataValidati
  QVariant::List or QVariant::StringList, the returned document
  document is invalid.
 
- \sa toVariant
+ \sa toVariant()
  */
 QJsonDocument QJsonDocument::fromVariant(const QVariant &variant)
 {
@@ -281,7 +281,7 @@ QJsonDocument QJsonDocument::fromVariant(const QVariant &variant)
  The returned variant will be a QVariantList if the document is
  a QJsonArray and a QVariantMap if the document is a QJsonObject.
 
- \sa fromVariant, QJsonValue::toVariant()
+ \sa fromVariant(), QJsonValue::toVariant()
  */
 QVariant QJsonDocument::toVariant() const
 {
@@ -297,7 +297,7 @@ QVariant QJsonDocument::toVariant() const
 /*!
  Converts the QJsonDocument to a UTF-8 encoded JSON document.
 
- \sa fromJson
+ \sa fromJson()
  */
 QByteArray QJsonDocument::toJson() const
 {
@@ -316,10 +316,15 @@ QByteArray QJsonDocument::toJson() const
 
 /*!
  Parses a UTF-8 encoded JSON document and creates a QJsonDocument
- from it. isNull() will return \c false if no error was encountered during
+ from it.
+
+ \a json contains the json document to be parsed.
+
+ The optional \a error variable can be used to pass in a QJsonParseError data
+ structure that will contain information about possible errors encountered during
  parsing.
 
- \sa toJson
+ \sa toJson(), QJsonParseError
  */
 QJsonDocument QJsonDocument::fromJson(const QByteArray &json, QJsonParseError *error)
 {
@@ -348,7 +353,7 @@ bool QJsonDocument::isEmpty() const
  or computers. fromBinaryData() can be used to convert it back into a
  JSON document.
 
- \sa fromBinaryData
+ \sa fromBinaryData()
  */
 QByteArray QJsonDocument::toBinaryData() const
 {
@@ -392,7 +397,7 @@ bool QJsonDocument::isObject() const
     Returns an empty object if the document contains an
     array.
 
-    \sa isObject, array, setObject
+    \sa isObject(), array(), setObject()
  */
 QJsonObject QJsonDocument::object() const
 {
@@ -410,7 +415,7 @@ QJsonObject QJsonDocument::object() const
     Returns an empty array if the document contains an
     object.
 
-    \sa isArray, object, setArray
+    \sa isArray(), object(), setArray()
  */
 QJsonArray QJsonDocument::array() const
 {
@@ -425,7 +430,7 @@ QJsonArray QJsonDocument::array() const
 /*!
     Sets \a object as the main object of this document.
 
-    \sa setArray, object
+    \sa setArray(), object()
  */
 void QJsonDocument::setObject(const QJsonObject &object)
 {
@@ -452,7 +457,7 @@ void QJsonDocument::setObject(const QJsonObject &object)
 /*!
     Sets \a array as the main object of this document.
 
-    \sa setObject, array
+    \sa setObject(), array()
  */
 void QJsonDocument::setArray(const QJsonArray &array)
 {
diff --git a/src/corelib/json/qjsonobject.cpp b/src/corelib/json/qjsonobject.cpp
index 8801e9c96d..c60b2215c7 100644
--- a/src/corelib/json/qjsonobject.cpp
+++ b/src/corelib/json/qjsonobject.cpp
@@ -72,6 +72,37 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
+    \typedef QJsonObject::Iterator
+
+    Qt-style synonym for QJsonObject::iterator.
+*/
+
+/*!
+    \typedef QJsonObject::ConstIterator
+
+    Qt-style synonym for QJsonObject::const_iterator.
+*/
+
+/*!
+    \typedef QJsonObject::key_type
+
+    Typedef for QString. Provided for STL compatibility.
+*/
+
+/*!
+    \typedef QJsonObject::mapped_type
+
+    Typedef for QJsonValue. Provided for STL compatibility.
+*/
+
+/*!
+    \typedef QJsonObject::size_type
+
+    Typedef for int. Provided for STL compatibility.
+*/
+
+
+/*!
     Constructs an empty JSON object
 
     \sa isEmpty()
@@ -754,7 +785,7 @@ QJsonObject::const_iterator QJsonObject::constFind(const QString &key) const
     Multiple iterators can be used on the same object. Existing iterators
     will however become dangling if the object gets modified.
 
-    \sa QJsonObject::iterator, QJsonObjectIterator
+    \sa QJsonObject::iterator
 */
 
 /*! \typedef QJsonObject::const_iterator::difference_type
@@ -818,6 +849,7 @@ QJsonObject::const_iterator QJsonObject::constFind(const QString &key) const
 */
 
 /*! \fn bool QJsonObject::const_iterator::operator==(const const_iterator &other) const
+    \fn bool QJsonObject::const_iterator::operator==(const iterator &other) const
 
     Returns \c true if \a other points to the same item as this
     iterator; otherwise returns \c false.
@@ -826,6 +858,7 @@ QJsonObject::const_iterator QJsonObject::constFind(const QString &key) const
 */
 
 /*! \fn bool QJsonObject::const_iterator::operator!=(const const_iterator &other) const
+    \fn bool QJsonObject::const_iterator::operator!=(const iterator &other) const
 
     Returns \c true if \a other points to a different item than this
     iterator; otherwise returns \c false.
@@ -983,16 +1016,6 @@ void QJsonObject::setValueAt(int i, const QJsonValue &val)
     insert(e->key(), val);
 }
 
-/*! \typedef QJsonObject::Iterator
-
-    Qt-style synonym for QJsonObject::iterator.
-*/
-
-/*! \typedef QJsonObject::ConstIterator
-
-    Qt-style synonym for QJsonObject::const_iterator.
-*/
-
 #ifndef QT_NO_DEBUG_STREAM
 QDebug operator<<(QDebug dbg, const QJsonObject &o)
 {
diff --git a/src/corelib/json/qjsonparser.cpp b/src/corelib/json/qjsonparser.cpp
index 4bec3fdd82..4633915e30 100644
--- a/src/corelib/json/qjsonparser.cpp
+++ b/src/corelib/json/qjsonparser.cpp
@@ -107,7 +107,27 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
+    \variable QJsonParseError::error
+
+    Contains the type of the parse error. Is equal to QJsonParseError::NoError if the document
+    was parsed correctly.
+
+    \sa ParseError, errorString()
+*/
+
+
+/*!
+    \variable QJsonParseError::offset
+
+    Contains the offset in the input string where the parse error occurred.
+
+    \sa error, errorString()
+*/
+
+/*!
   Returns the human-readable message appropriate to the reported JSON parsing error.
+
+  \sa error
  */
 QString QJsonParseError::errorString() const
 {
diff --git a/src/corelib/json/qjsonvalue.cpp b/src/corelib/json/qjsonvalue.cpp
index bde3323fa0..91318a4ba9 100644
--- a/src/corelib/json/qjsonvalue.cpp
+++ b/src/corelib/json/qjsonvalue.cpp
@@ -255,6 +255,60 @@ QJsonValue &QJsonValue::operator =(const QJsonValue &other)
 }
 
 /*!
+    \fn bool QJsonValue::isNull() const
+
+    Returns true if the value is null.
+*/
+
+/*!
+    \fn bool QJsonValue::isBool() const
+
+    Returns true if the value contains a boolean.
+
+    \sa toBool()
+ */
+
+/*!
+    \fn bool QJsonValue::isDouble() const
+
+    Returns true if the value contains a double.
+
+    \sa toDouble()
+ */
+
+/*!
+    \fn bool QJsonValue::isString() const
+
+    Returns true if the value contains a string.
+
+    \sa toString()
+ */
+
+/*!
+    \fn bool QJsonValue::isArray() const
+
+    Returns true if the value contains an array.
+
+    \sa toArray()
+ */
+
+/*!
+    \fn bool QJsonValue::isObject() const
+
+    Returns true if the value contains an object.
+
+    \sa toObject()
+ */
+
+/*!
+    \fn bool QJsonValue::isUndefined() const
+
+    Returns true if the value is undefined. This can happen in certain
+    error cases as e.g. accessing a non existing key in a QJsonObject.
+ */
+
+
+/*!
     Converts \a variant to a QJsonValue and returns it.
 
     The conversion will convert QVariant types as follows:
@@ -369,7 +423,7 @@ QJsonValue::Type QJsonValue::type() const
 /*!
     Converts the value to a bool and returns it.
 
-    If type() is not bool, the defaultValue will be returned.
+    If type() is not bool, the \a defaultValue will be returned.
  */
 bool QJsonValue::toBool(bool defaultValue) const
 {
@@ -381,7 +435,7 @@ bool QJsonValue::toBool(bool defaultValue) const
 /*!
     Converts the value to a double and returns it.
 
-    If type() is not Double, the defaultValue will be returned.
+    If type() is not Double, the \a defaultValue will be returned.
  */
 double QJsonValue::toDouble(double defaultValue) const
 {
@@ -393,7 +447,7 @@ double QJsonValue::toDouble(double defaultValue) const
 /*!
     Converts the value to a QString and returns it.
 
-    If type() is not String, the defaultValue will be returned.
+    If type() is not String, the \a defaultValue will be returned.
  */
 QString QJsonValue::toString(const QString &defaultValue) const
 {
@@ -407,7 +461,7 @@ QString QJsonValue::toString(const QString &defaultValue) const
 /*!
     Converts the value to an array and returns it.
 
-    If type() is not Array, the defaultValue will be returned.
+    If type() is not Array, the \a defaultValue will be returned.
  */
 QJsonArray QJsonValue::toArray(const QJsonArray &defaultValue) const
 {
@@ -432,7 +486,7 @@ QJsonArray QJsonValue::toArray() const
 /*!
     Converts the value to an object and returns it.
 
-    If type() is not Object, the defaultValue will be returned.
+    If type() is not Object, the \a defaultValue will be returned.
  */
 QJsonObject QJsonValue::toObject(const QJsonObject &defaultValue) const
 {