Add documentation for QJsonObject

Change-Id: Ia5a129749b3eb831e84d217cb42607003e5ef841
Sanity-Review: Qt Sanity Bot <qt_sanity_bot@ovi.com>
Reviewed-by: Denis Dzyubenko <denis.dzyubenko@nokia.com>

1 files changed, 616 insertions, 0 deletions

diff --git a/src/qjsonobject.cpp b/src/qjsonobject.cpp
index d855eee..b3ddfe4 100644
--- a/src/qjsonobject.cpp
+++ b/src/qjsonobject.cpp
@@ -49,11 +49,38 @@
 
 namespace QtJson {
 
+/*!
+    \class QJsonObject
+    \ingroup json
+    \reentrant
+    \since 5.0
+
+    \brief The QJsonObject class encapsulates a JSON object.
+
+    A JSON object is a list of key value pairs, where the keys are unique strings
+    and the values are represented by a QJsonValue.
+
+    A QJsonObject can be converted from and to a QVariantMap, you can query the
+    number of key/value pairs with size(), insert() and remove() entries from it
+    and iterate over it's content using the standard C++ iterator pattern.
+
+    QJsonObject is an implicitly shared class, and shares the data with the document
+    it has been created from as long as it is not being modified.
+*/
+
+/*!
+    Constructs an empty JSON object
+
+    \sa isEmpty
+ */
 QJsonObject::QJsonObject()
     : d(0), o(0)
 {
 }
 
+/*!
+    \internal
+ */
 QJsonObject::QJsonObject(Private::Data *data, Private::Object *object)
     : d(data), o(object)
 {
@@ -63,12 +90,21 @@ QJsonObject::QJsonObject(Private::Data *data, Private::Object *object)
 }
 
 
+/*!
+    Destroys the object.
+ */
 QJsonObject::~QJsonObject()
 {
     if (d && !d->ref.deref())
         delete d;
 }
 
+/*!
+    Creates a copy of \a other.
+
+    Since QJsonObject is implicitly shared, the copy is shallow
+    as long as the object doesn't get modified.
+ */
 QJsonObject::QJsonObject(const QJsonObject &other)
 {
     d = other.d;
@@ -77,6 +113,9 @@ QJsonObject::QJsonObject(const QJsonObject &other)
         d->ref.ref();
 }
 
+/*!
+    Assigns \a other to this object.
+ */
 QJsonObject &QJsonObject::operator =(const QJsonObject &other)
 {
     if (d != other.d) {
@@ -91,6 +130,14 @@ QJsonObject &QJsonObject::operator =(const QJsonObject &other)
     return *this;
 }
 
+/*!
+    Converts the variant map \a map to a QJsonObject.
+
+    The keys in \a map will be used as the keys in the JSON object,
+    and the QVariant values will be converted to JSON values.
+
+    \sa toVariantMap, QJsonValue::fromVariant
+ */
 QJsonObject QJsonObject::fromVariantMap(const QVariantMap &map)
 {
     // ### this is implemented the trivial way, not the most efficient way
@@ -101,6 +148,11 @@ QJsonObject QJsonObject::fromVariantMap(const QVariantMap &map)
     return object;
 }
 
+/*!
+    Converts this object to a QVariantMap.
+
+    \returns the created map.
+ */
 QVariantMap QJsonObject::toVariantMap() const
 {
     QVariantMap map;
@@ -111,6 +163,9 @@ QVariantMap QJsonObject::toVariantMap() const
     return map;
 }
 
+/*!
+    \returns a list of all keys in this object.
+ */
 QStringList QJsonObject::keys() const
 {
     if (!d)
@@ -126,6 +181,10 @@ QStringList QJsonObject::keys() const
     return keys;
 }
 
+/*!
+    \returns the size of this object, ie. the number of
+    key/value pairs stored in it.
+ */
 int QJsonObject::size() const
 {
     if (!d)
@@ -134,6 +193,11 @@ int QJsonObject::size() const
     return o->length;
 }
 
+/*!
+    \returns true if the object is empty. This is the same as size() == 0.
+
+    \sa size
+ */
 bool QJsonObject::isEmpty() const
 {
     if (!d)
@@ -142,6 +206,13 @@ bool QJsonObject::isEmpty() const
     return !o->length;
 }
 
+/*!
+    \returns a QJsonValue representing the value for the key \a key.
+
+    The returned QJsonValue is Undefined, if the key does not exist.
+
+    \sa setValue, QJsonValue, QJsonValue::isUndefined
+ */
 QJsonValue QJsonObject::value(const QString &key) const
 {
     if (!d)
@@ -155,11 +226,31 @@ QJsonValue QJsonObject::value(const QString &key) const
     return QJsonValue(QJsonValue::Undefined);
 }
 
+/*!
+    \returns a QJsonValue representing the value for the key \a key.
+
+    This does the same as value().
+
+    The returned QJsonValue is Undefined, if the key does not exist.
+
+    \sa value, setValue, QJsonValue, QJsonValue::isUndefined
+ */
 QJsonValue QJsonObject::operator [](const QString &key) const
 {
     return value(key);
 }
 
+/*!
+    \returns a reference to the value for \a key.
+
+    The return value is of type QJsonValueRef, a helper class for QJsonArray
+    and QJsonObject. When you get an object of type QJsonValueRef, you can
+    use it as if it were a QJsonValue &. If you assign to it, the assignment
+    will apply to the character in the QJsonArray of QJsonObject from which
+    you got the reference.
+
+    \sa setValue, value
+ */
 QJsonValueRef QJsonObject::operator [](const QString &key)
 {
     int index = o ? o->indexOf(key) : -1;
@@ -170,6 +261,19 @@ QJsonValueRef QJsonObject::operator [](const QString &key)
     return QJsonValueRef(this, index);
 }
 
+/*!
+    Inserts a new item with the key \a key and a value of \a value.
+
+    If there is already an item with the key \a key, that item's value
+    is replaced with \a value.
+
+    \returns an iterator pointing to the inserted item.
+
+    If the value is QJsonValue::Undefined, it will cause the key to get removed
+    from the object. The returned iterator will then point to end()
+
+    \sa remove, take, QJsonObject::iterator, end
+ */
 QJsonObject::iterator QJsonObject::insert(const QString &key, const QJsonValue &value)
 {
     if (value.t == QJsonValue::Undefined) {
@@ -212,6 +316,11 @@ QJsonObject::iterator QJsonObject::insert(const QString &key, const QJsonValue &
     return iterator(this, pos);
 }
 
+/*!
+    Removes \a key from the object.
+
+    \sa insert, take
+ */
 void QJsonObject::remove(const QString &key)
 {
     if (!d)
@@ -228,6 +337,15 @@ void QJsonObject::remove(const QString &key)
         compact();
 }
 
+/*!
+    Removes \a key from the object.
+
+    \returns a QJsonValue containing the value referenced by \a key.
+    If \a key was not contained in the object, the returned QJsonValue
+    is Undefined.
+
+    \sa insert, remove, QJsonValue
+ */
 QJsonValue QJsonObject::take(const QString &key)
 {
     if (!o)
@@ -246,6 +364,11 @@ QJsonValue QJsonObject::take(const QString &key)
     return QJsonValue(d, o, e->value);
 }
 
+/*!
+    \returns true if the object contains key \a key.
+
+    \sa insert, remove, take
+ */
 bool QJsonObject::contains(const QString &key) const
 {
     if (!o)
@@ -254,6 +377,9 @@ bool QJsonObject::contains(const QString &key) const
     return o->indexOf(key) >= 0;
 }
 
+/*!
+    \returns true if \a other is equal to this object
+ */
 bool QJsonObject::operator==(const QJsonObject &other) const
 {
     if (o == other.o)
@@ -276,11 +402,21 @@ bool QJsonObject::operator==(const QJsonObject &other) const
     return true;
 }
 
+/*!
+    \returns true if \a other is not equal to this object
+ */
 bool QJsonObject::operator!=(const QJsonObject &other) const
 {
     return !(*this == other);
 }
 
+/*!
+    Removes the (key, value) pair pointed to by the iterator \a it
+    from the map, and returns an iterator to the next item in the
+    map.
+
+    \sa remove()
+ */
 QJsonObject::iterator QJsonObject::erase(QJsonObject::iterator it)
 {
     Q_ASSERT(d && d->ref.load() == 1);
@@ -298,6 +434,13 @@ QJsonObject::iterator QJsonObject::erase(QJsonObject::iterator it)
     return it;
 }
 
+/*!
+    Returns an iterator pointing to the item with key \a key in the
+    map.
+
+    If the map contains no item with key \a key, the function
+    returns end().
+ */
 QJsonObject::iterator QJsonObject::find(const QString &key)
 {
     int index = o ? o->indexOf(key) : 0;
@@ -306,6 +449,18 @@ QJsonObject::iterator QJsonObject::find(const QString &key)
     return iterator(this, index);
 }
 
+/*! \fn QJsonObject::const_iterator QJsonObject::find(const Key &key) const
+
+    \overload
+*/
+
+/*!
+    Returns an const iterator pointing to the item with key \a key in the
+    map.
+
+    If the map contains no item with key \a key, the function
+    returns constEnd().
+ */
 QJsonObject::const_iterator QJsonObject::constFind(const QString &key) const
 {
     int index = o ? o->indexOf(key) : 0;
@@ -314,6 +469,434 @@ QJsonObject::const_iterator QJsonObject::constFind(const QString &key) const
     return const_iterator(this, index);
 }
 
+/*! \fn int QJsonObject::count() const
+
+    \overload
+
+    Same as size().
+*/
+
+/*! \fn QJsonObject::iterator QJsonObject::begin()
+
+    Returns an \l{STL-style iterator} pointing to the first item in
+    the object.
+
+    \sa constBegin(), end()
+*/
+
+/*! \fn QJsonObject::const_iterator QJsonObject::begin() const
+
+    \overload
+*/
+
+/*! \fn QJsonObject::const_iterator QJsonObject::constBegin() const
+
+    Returns a const \l{STL-style iterator} pointing to the first item
+    in the object.
+
+    \sa begin(), constEnd()
+*/
+
+/*! \fn QJsonObject::iterator QJsonObject::end()
+
+    Returns an \l{STL-style iterator} pointing to the imaginary item
+    after the last item in the object.
+
+    \sa begin(), constEnd()
+*/
+
+/*! \fn QJsonObject::const_iterator QJsonObject::end() const
+
+    \overload
+*/
+
+/*! \fn QJsonObject::const_iterator QJsonObject::constEnd() const
+
+    Returns a const \l{STL-style iterator} pointing to the imaginary
+    item after the last item in the object.
+
+    \sa constBegin(), end()
+*/
+
+/*!
+    \fn bool QJsonObject::empty() const
+
+    This function is provided for STL compatibility. It is equivalent
+    to isEmpty(), returning true if the object is empty; otherwise
+    returning false.
+*/
+
+/*! \class QJsonObject::iterator
+    \brief The QJsonObject::iterator class provides an STL-style non-const iterator for QJsonObject.
+
+    QJsonObject::iterator allows you to iterate over a QJsonObject
+    and to modify the value (but not the key) stored under
+    a particular key. If you want to iterate over a const QJsonObject, you
+    should use QJsonObject::const_iterator. It is generally good practice to
+    use QJsonObject::const_iterator on a non-const QJsonObject as well, unless you
+    need to change the QJsonObject through the iterator. Const iterators are
+    slightly faster, and can improve code readability.
+
+    The default QJsonObject::iterator constructor creates an uninitialized
+    iterator. You must initialize it using a QJsonObject function like
+    QJsonObject::begin(), QJsonObject::end(), or QJsonObject::find() before you can
+    start iterating.
+
+    Multiple iterators can be used on the same object. Existing iterators will however
+    become dangling once the object gets modified.
+
+    \sa QJsonObject::const_iterator
+*/
+
+/*! \typedef QJsonObject::iterator::difference_type
+
+    \internal
+*/
+
+/*! \typedef QJsonObject::iterator::iterator_category
+
+  A synonym for \e {std::bidirectional_iterator_tag} indicating
+  this iterator is a bidirectional iterator.
+*/
+
+/*! \typedef QJsonObject::iterator::reference
+
+    \internal
+*/
+
+/*! \typedef QJsonObject::iterator::value_type
+
+    \internal
+*/
+
+/*! \fn QJsonObject::iterator::iterator()
+
+    Constructs an uninitialized iterator.
+
+    Functions like key(), value(), and operator++() must not be
+    called on an uninitialized iterator. Use operator=() to assign a
+    value to it before using it.
+
+    \sa QJsonObject::begin() QJsonObject::end()
+*/
+
+/*! \fn QString QJsonObject::iterator::key() const
+
+    Returns the current item's key.
+
+    There is no direct way of changing an item's key through an
+    iterator, although it can be done by calling QJsonObject::erase()
+    followed by QJsonObject::insert().
+
+    \sa value()
+*/
+
+/*! \fn QJsonValueRef QJsonObject::iterator::value() const
+
+    Returns a modifiable reference to the current item's value.
+
+    You can change the value of an item by using value() on
+    the left side of an assignment.
+
+    The return value is of type QJsonValueRef, a helper class for QJsonArray
+    and QJsonObject. When you get an object of type QJsonValueRef, you can
+    use it as if it were a QJsonValue &. If you assign to it, the assignment
+    will apply to the character in the QJsonArray of QJsonObject from which
+    you got the reference.
+
+    \sa key(), operator*()
+*/
+
+/*! \fn QJsonValueRef QJsonObject::iterator::operator*() const
+
+    Returns a modifiable reference to the current item's value.
+
+    Same as value().
+
+    The return value is of type QJsonValueRef, a helper class for QJsonArray
+    and QJsonObject. When you get an object of type QJsonValueRef, you can
+    use it as if it were a QJsonValue &. If you assign to it, the assignment
+    will apply to the character in the QJsonArray of QJsonObject from which
+    you got the reference.
+
+    \sa key()
+*/
+
+/*!
+    \fn bool QJsonObject::iterator::operator==(const iterator &other) const
+    \fn bool QJsonObject::iterator::operator==(const const_iterator &other) const
+
+    Returns true if \a other points to the same item as this
+    iterator; otherwise returns false.
+
+    \sa operator!=()
+*/
+
+/*!
+    \fn bool QJsonObject::iterator::operator!=(const iterator &other) const
+    \fn bool QJsonObject::iterator::operator!=(const const_iterator &other) const
+
+    Returns true if \a other points to a different item than this
+    iterator; otherwise returns false.
+
+    \sa operator==()
+*/
+
+/*! \fn QJsonObject::iterator QJsonObject::iterator::operator++()
+
+    The prefix ++ operator (\c{++i}) advances the iterator to the
+    next item in the object and returns an iterator to the new current
+    item.
+
+    Calling this function on QJsonObject::end() leads to undefined results.
+
+    \sa operator--()
+*/
+
+/*! \fn QJsonObject::iterator QJsonObject::iterator::operator++(int)
+
+    \overload
+
+    The postfix ++ operator (\c{i++}) advances the iterator to the
+    next item in the object and returns an iterator to the previously
+    current item.
+*/
+
+/*! \fn QJsonObject::iterator QJsonObject::iterator::operator--()
+
+    The prefix -- operator (\c{--i}) makes the preceding item
+    current and returns an iterator pointing to the new current item.
+
+    Calling this function on QJsonObject::begin() leads to undefined
+    results.
+
+    \sa operator++()
+*/
+
+/*! \fn QJsonObject::iterator QJsonObject::iterator::operator--(int)
+
+    \overload
+
+    The postfix -- operator (\c{i--}) makes the preceding item
+    current and returns an iterator pointing to the previously
+    current item.
+*/
+
+/*! \fn QJsonObject::iterator QJsonObject::iterator::operator+(int j) const
+
+    Returns an iterator to the item at \a j positions forward from
+    this iterator. (If \a j is negative, the iterator goes backward.)
+
+    \sa operator-()
+
+*/
+
+/*! \fn QJsonObject::iterator QJsonObject::iterator::operator-(int j) const
+
+    Returns an iterator to the item at \a j positions backward from
+    this iterator. (If \a j is negative, the iterator goes forward.)
+
+    \sa operator+()
+*/
+
+/*! \fn QJsonObject::iterator &QJsonObject::iterator::operator+=(int j)
+
+    Advances the iterator by \a j items. (If \a j is negative, the
+    iterator goes backward.)
+
+    \sa operator-=(), operator+()
+*/
+
+/*! \fn QJsonObject::iterator &QJsonObject::iterator::operator-=(int j)
+
+    Makes the iterator go back by \a j items. (If \a j is negative,
+    the iterator goes forward.)
+
+    \sa operator+=(), operator-()
+*/
+
+/*! \class QJsonObject::const_iterator
+    \brief The QJsonObject::const_iterator class provides an STL-style const iterator for QJsonObject.
+
+    QJsonObject::const_iterator allows you to iterate over a QJsonObject.
+    If you want to modify the QJsonObject as you iterate
+    over it, you must use QJsonObject::iterator instead. It is generally
+    good practice to use QJsonObject::const_iterator on a non-const QJsonObject as
+    well, unless you need to change the QJsonObject through the iterator.
+    Const iterators are slightly faster, and can improve code
+    readability.
+
+    The default QJsonObject::const_iterator constructor creates an
+    uninitialized iterator. You must initialize it using a QJsonObject
+    function like QJsonObject::constBegin(), QJsonObject::constEnd(), or
+    QJsonObject::find() before you can start iterating.
+
+    Multiple iterators can be used on the same object. Existing iterators
+    will however become dangling if the object gets modified.
+
+    \sa QJsonObject::iterator, QJsonObjectIterator
+*/
+
+/*! \typedef QJsonObject::const_iterator::difference_type
+
+    \internal
+*/
+
+/*! \typedef QJsonObject::const_iterator::iterator_category
+
+  A synonym for \e {std::bidirectional_iterator_tag} indicating
+  this iterator is a bidirectional iterator.
+*/
+
+/*! \typedef QJsonObject::const_iterator::reference
+
+    \internal
+*/
+
+/*! \typedef QJsonObject::const_iterator::value_type
+
+    \internal
+*/
+
+/*! \fn QJsonObject::const_iterator::const_iterator()
+
+    Constructs an uninitialized iterator.
+
+    Functions like key(), value(), and operator++() must not be
+    called on an uninitialized iterator. Use operator=() to assign a
+    value to it before using it.
+
+    \sa QJsonObject::constBegin() QJsonObject::constEnd()
+*/
+
+/*! \fn QJsonObject::const_iterator::const_iterator(const iterator &other)
+
+    Constructs a copy of \a other.
+*/
+
+/*! \fn QString QJsonObject::const_iterator::key() const
+
+    Returns the current item's key.
+
+    \sa value()
+*/
+
+/*! \fn QJsonValue QJsonObject::const_iterator::value() const
+
+    Returns the current item's value.
+
+    \sa key(), operator*()
+*/
+
+/*! \fn QJsonValue QJsonObject::const_iterator::operator*() const
+
+    Returns the current item's value.
+
+    Same as value().
+
+    \sa key()
+*/
+
+/*! \fn bool QJsonObject::const_iterator::operator==(const const_iterator &other) const
+
+    Returns true if \a other points to the same item as this
+    iterator; otherwise returns false.
+
+    \sa operator!=()
+*/
+
+/*! \fn bool QJsonObject::const_iterator::operator!=(const const_iterator &other) const
+
+    Returns true if \a other points to a different item than this
+    iterator; otherwise returns false.
+
+    \sa operator==()
+*/
+
+/*! \fn QJsonObject::const_iterator QJsonObject::const_iterator::operator++()
+
+    The prefix ++ operator (\c{++i}) advances the iterator to the
+    next item in the object and returns an iterator to the new current
+    item.
+
+    Calling this function on QJsonObject::end() leads to undefined results.
+
+    \sa operator--()
+*/
+
+/*! \fn QJsonObject::const_iterator QJsonObject::const_iterator::operator++(int)
+
+    \overload
+
+    The postfix ++ operator (\c{i++}) advances the iterator to the
+    next item in the object and returns an iterator to the previously
+    current item.
+*/
+
+/*! \fn QJsonObject::const_iterator &QJsonObject::const_iterator::operator--()
+
+    The prefix -- operator (\c{--i}) makes the preceding item
+    current and returns an iterator pointing to the new current item.
+
+    Calling this function on QJsonObject::begin() leads to undefined
+    results.
+
+    \sa operator++()
+*/
+
+/*! \fn QJsonObject::const_iterator QJsonObject::const_iterator::operator--(int)
+
+    \overload
+
+    The postfix -- operator (\c{i--}) makes the preceding item
+    current and returns an iterator pointing to the previously
+    current item.
+*/
+
+/*! \fn QJsonObject::const_iterator QJsonObject::const_iterator::operator+(int j) const
+
+    Returns an iterator to the item at \a j positions forward from
+    this iterator. (If \a j is negative, the iterator goes backward.)
+
+    This operation can be slow for large \a j values.
+
+    \sa operator-()
+*/
+
+/*! \fn QJsonObject::const_iterator QJsonObject::const_iterator::operator-(int j) const
+
+    Returns an iterator to the item at \a j positions backward from
+    this iterator. (If \a j is negative, the iterator goes forward.)
+
+    This operation can be slow for large \a j values.
+
+    \sa operator+()
+*/
+
+/*! \fn QJsonObject::const_iterator &QJsonObject::const_iterator::operator+=(int j)
+
+    Advances the iterator by \a j items. (If \a j is negative, the
+    iterator goes backward.)
+
+    This operation can be slow for large \a j values.
+
+    \sa operator-=(), operator+()
+*/
+
+/*! \fn QJsonObject::const_iterator &QJsonObject::const_iterator::operator-=(int j)
+
+    Makes the iterator go back by \a j items. (If \a j is negative,
+    the iterator goes forward.)
+
+    This operation can be slow for large \a j values.
+
+    \sa operator+=(), operator-()
+*/
+
+
+/*!
+    \internal
+ */
 void QJsonObject::detach(uint reserve)
 {
     if (!d) {
@@ -333,6 +916,9 @@ void QJsonObject::detach(uint reserve)
     o = static_cast<Private::Object *>(d->header->root());
 }
 
+/*!
+    \internal
+ */
 void QJsonObject::compact() const
 {
     if (!d || !d->compactionCounter)
@@ -343,6 +929,9 @@ void QJsonObject::compact() const
     const_cast<QJsonObject *>(this)->o = static_cast<Private::Object *>(d->header->root());
 }
 
+/*!
+    \internal
+ */
 QString QJsonObject::keyAt(int i) const
 {
     Q_ASSERT(o && i >= 0 && i < (int)o->length);
@@ -351,6 +940,9 @@ QString QJsonObject::keyAt(int i) const
     return e->key();
 }
 
+/*!
+    \internal
+ */
 QJsonValue QJsonObject::valueAt(int i) const
 {
     if (!o || i < 0 || i >= (int)o->length)
@@ -360,6 +952,9 @@ QJsonValue QJsonObject::valueAt(int i) const
     return QJsonValue(d, o, e->value);
 }
 
+/*!
+    \internal
+ */
 void QJsonObject::setValueAt(int i, const QJsonValue &val)
 {
     Q_ASSERT(o && i >= 0 && i < (int)o->length);
@@ -368,6 +963,27 @@ 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.
+*/
+
+
+/*! \class QJsonObject::iterator
+    \ingroup json
+    \reentrant
+    \since 5.0
+
+    \brief The QJsonDocument::iterator class provides a way to iterate over q QJsonObject
+
+
+ */
+
 
 } // namespace QtJson