Add docs for QJsonArray

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

1 files changed, 684 insertions, 1 deletions

diff --git a/src/qjsonarray.cpp b/src/qjsonarray.cpp
index 70c6d3c..cfd77d1 100644
--- a/src/qjsonarray.cpp
+++ b/src/qjsonarray.cpp
@@ -51,23 +51,57 @@
 
 namespace QtJson {
 
+/*!
+    \class QJsonArray
+    \ingroup json
+    \reentrant
+    \since 5.0
+
+    \brief The QJsonArray class encapsulates a JSON array.
+
+    A JSON array is a list values. The list can be manipulated by inserting and
+    removing QJsonValue's from the array.
+
+    A QJsonArray can be converted from and to a QVariantList, you can query the
+    number of entries with size(), insert() and remove() entries from it
+    and iterate over it's content using the standard C++ iterator pattern.
+
+    QJsonArray 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.
+*/
+
+/*!
+    Creates an empty array.
+ */
 QJsonArray::QJsonArray()
     : d(0), a(0)
 {
 }
 
+/*!
+    \internal
+ */
 QJsonArray::QJsonArray(Private::Data *data, Private::Array *array)
     : d(data), a(array)
 {
     d->ref.ref();
 }
 
+/*!
+    Deletes the array
+ */
 QJsonArray::~QJsonArray()
 {
     if (d && !d->ref.deref())
         delete d;
 }
 
+/*!
+    Creates a copy of \a other.
+
+    Since QJsonArray is implicitly shared, the copy is shallow
+    as long as the object doesn't get modified.
+ */
 QJsonArray::QJsonArray(const QJsonArray &other)
 {
     d = other.d;
@@ -76,6 +110,9 @@ QJsonArray::QJsonArray(const QJsonArray &other)
         d->ref.ref();
 }
 
+/*!
+    Assigns \a other to this array.
+ */
 QJsonArray &QJsonArray::operator =(const QJsonArray &other)
 {
     if (d != other.d) {
@@ -90,6 +127,13 @@ QJsonArray &QJsonArray::operator =(const QJsonArray &other)
     return *this;
 }
 
+/*!
+    Converts the string list \a list to a QJsonArray.
+
+    The values in \a list will be converted to JSON values.
+
+    \sa toVariantList, QJsonValue::fromString
+ */
 QJsonArray QJsonArray::fromStringList(const QStringList &list)
 {
     QJsonArray array;
@@ -98,6 +142,13 @@ QJsonArray QJsonArray::fromStringList(const QStringList &list)
     return array;
 }
 
+/*!
+    Converts the variant list \a list to a QJsonArray.
+
+    The QVariant values in \a list will be converted to JSON values.
+
+    \sa toVariantList, QJsonValue::fromVariant
+ */
 QJsonArray QJsonArray::fromVariantList(const QVariantList &list)
 {
     QJsonArray array;
@@ -106,6 +157,11 @@ QJsonArray QJsonArray::fromVariantList(const QVariantList &list)
     return array;
 }
 
+/*!
+    Converts this object to a QVariantList.
+
+    \returns the created map.
+ */
 QVariantList QJsonArray::toVariantList() const
 {
     QVariantList list;
@@ -118,6 +174,10 @@ QVariantList QJsonArray::toVariantList() const
 }
 
 
+/*!
+    \returns the size of this object, ie. the number of
+    values stored in it.
+ */
 int QJsonArray::size() const
 {
     if (!d)
@@ -126,6 +186,11 @@ int QJsonArray::size() const
     return (int)a->length;
 }
 
+/*!
+    \returns true if the object is empty. This is the same as size() == 0.
+
+    \sa size
+ */
 bool QJsonArray::isEmpty() const
 {
     if (!d)
@@ -134,6 +199,12 @@ bool QJsonArray::isEmpty() const
     return !a->length;
 }
 
+/*!
+    \returns a QJsonValue representing the value for index \a i.
+
+    The returned QJsonValue is Undefined, if i is out of bounds.
+
+ */
 QJsonValue QJsonArray::at(int i) const
 {
     if (!a || i < 0 || i >= (int)a->length)
@@ -142,26 +213,58 @@ QJsonValue QJsonArray::at(int i) const
     return QJsonValue(d, a, a->at(i));
 }
 
+/*!
+    Returns the first value stored in the array.
+
+    Same as at(0).
+
+    \sa at
+ */
 QJsonValue QJsonArray::first() const
 {
     return at(0);
 }
 
+/*!
+    Returns the last value stored in the array.
+
+    Same as at(size() - 1).
+
+    \sa at
+ */
 QJsonValue QJsonArray::last() const
 {
     return at(a ? (a->length - 1) : 0);
 }
 
+/*!
+    Inserts \a value at the beginning of the array.
+
+    This is the same as array.insert(0, \a value).
+
+    \sa append(), insert()
+ */
 void QJsonArray::prepend(const QJsonValue &value)
 {
     insert(0, value);
 }
 
+/*!
+    Inserts \a value at the end of the array.
+
+    \sa prepend(), insert()
+ */
 void QJsonArray::append(const QJsonValue &value)
 {
     insert(a ? a->length : 0, value);
 }
 
+/*!
+    Removes the value at index position \a i. \a i must be a valid
+    index position in the array (i.e., 0 <= \a i < size()).
+
+    \sa insert(), replace()
+ */
 void QJsonArray::removeAt(int i)
 {
     if (!a || i < 0 || i >= (int)a->length)
@@ -174,6 +277,34 @@ void QJsonArray::removeAt(int i)
         compact();
 }
 
+/*! \fn void QJsonArray::removeFirst()
+
+    Removes the first item in the array. Calling this function is
+    equivalent to calling removeAt(0). The array must not be empty. If
+    the array can be empty, call isEmpty() before calling this
+    function.
+
+    \sa removeAt(), takeFirst()
+*/
+
+/*! \fn void QJsonArray::removeLast()
+
+    Removes the last item in the array. Calling this function is
+    equivalent to calling removeAt(size() - 1). The array must not be
+    empty. If the array can be empty, call isEmpty() before calling
+    this function.
+
+    \sa removeAt(), takeLast()
+*/
+
+/*!
+    Removes the item at index position \a i and returns it. \a i must
+    be a valid index position in the array (i.e., 0 <= \a i < size()).
+
+    If you don't use the return value, removeAt() is more efficient.
+
+    \sa removeAt()
+ */
 QJsonValue QJsonArray::takeAt(int i)
 {
     if (!a || i < 0 || i >= (int)a->length)
@@ -189,6 +320,13 @@ QJsonValue QJsonArray::takeAt(int i)
     return v;
 }
 
+/*!
+    Inserts \a value at index position \a i in the array. If \a i
+    is 0, the value is prepended to the array. If \a i is size(), the
+    value is appended to the array.
+
+    \sa append(), prepend(), replace(), removeAt()
+ */
 void QJsonArray::insert(int i, const QJsonValue &value)
 {
     Q_ASSERT (i >= 0 && i <= (int)(a ? a->length : 0));
@@ -211,6 +349,12 @@ void QJsonArray::insert(int i, const QJsonValue &value)
         value.copyData((char *)a + valueOffset, compressed);
 }
 
+/*!
+    Replaces the item at index position \a i with \a value. \a i must
+    be a valid index position in the array (i.e., 0 <= \a i < size()).
+
+    \sa operator[](), removeAt()
+ */
 void QJsonArray::replace(int i, const QJsonValue &value)
 {
     Q_ASSERT (a && i >= 0 && i < (int)(a->length));
@@ -237,7 +381,12 @@ void QJsonArray::replace(int i, const QJsonValue &value)
         compact();
 }
 
-bool QJsonArray::contains(const QJsonValue &element) const
+/*!
+    Returns true if the array contains an occurrence of \a value, otherwise false.
+
+    \sa count()
+ */
+bool QJsonArray::contains(const QJsonValue &value) const
 {
     for (int i = 0; i < size(); i++) {
         if (at(i) == element)
@@ -246,17 +395,38 @@ bool QJsonArray::contains(const QJsonValue &element) const
     return false;
 }
 
+/*!
+    Returns the value at index position \a i as a modifiable reference.
+    \a i must be a valid index position in the array (i.e., 0 <= \a i <
+    size()).
+
+    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 at(), value()
+ */
 QJsonValueRef QJsonArray::operator [](int i)
 {
     Q_ASSERT(a && i >= 0 && i < (int)a->length);
     return QJsonValueRef(this, i);
 }
 
+/*!
+    \overload
+
+    Same as at().
+ */
 QJsonValue QJsonArray::operator[](int i) const
 {
     return at(i);
 }
 
+/*!
+    Returns true if this array is equal to \a other.
+ */
 bool QJsonArray::operator==(const QJsonArray &other) const
 {
     if (a == other.a)
@@ -276,11 +446,521 @@ bool QJsonArray::operator==(const QJsonArray &other) const
     return true;
 }
 
+/*!
+    Returns true if this array is not equal to \a other.
+ */
 bool QJsonArray::operator!=(const QJsonArray &other) const
 {
     return !(*this == other);
 }
 
+/*! \fn QJsonArray::iterator QJsonArray::begin()
+
+    Returns an \l{STL-style iterator} pointing to the first item in
+    the array.
+
+    \sa constBegin(), end()
+*/
+
+/*! \fn QJsonArray::const_iterator QJsonArray::begin() const
+
+    \overload
+*/
+
+/*! \fn QJsonArray::const_iterator QJsonArray::constBegin() const
+
+    Returns a const \l{STL-style iterator} pointing to the first item
+    in the array.
+
+    \sa begin(), constEnd()
+*/
+
+/*! \fn QJsonArray::iterator QJsonArray::end()
+
+    Returns an \l{STL-style iterator} pointing to the imaginary item
+    after the last item in the array.
+
+    \sa begin(), constEnd()
+*/
+
+/*! \fn const_iterator QJsonArray::end() const
+
+    \overload
+*/
+
+/*! \fn QJsonArray::const_iterator QJsonArray::constEnd() const
+
+    Returns a const \l{STL-style iterator} pointing to the imaginary
+    item after the last item in the array.
+
+    \sa constBegin(), end()
+*/
+
+/*! \fn void QJsonArray::push_back(const T &value)
+
+    This function is provided for STL compatibility. It is equivalent
+    to \l{QJsonArray::append()}{append(\a value)}.
+*/
+
+/*! \fn void QJsonArray::push_front(const T &value)
+
+    This function is provided for STL compatibility. It is equivalent
+    to \l{QJsonArray::prepend()}{prepend(\a value)}.
+*/
+
+/*! \fn void QJsonArray::pop_front()
+
+    This function is provided for STL compatibility. It is equivalent
+    to removeFirst(). The array must not be empty. If the array can be
+    empty, call isEmpty() before calling this function.
+*/
+
+/*! \fn void QJsonArray::pop_back()
+
+    This function is provided for STL compatibility. It is equivalent
+    to removeLast(). The array must not be empty. If the array can be
+    empty, call isEmpty() before calling this function.
+*/
+
+/*! \fn bool QJsonArray::empty() const
+
+    This function is provided for STL compatibility. It is equivalent
+    to isEmpty() and returns true if the array is empty.
+*/
+
+/*! \class QJsonArray::iterator
+    \brief The QJsonArray::iterator class provides an STL-style non-const iterator for QJsonArray.
+
+    QJsonArray::iterator allows you to iterate over a QJsonArray
+    and to modify the array item associated with the
+    iterator. If you want to iterate over a const QJsonArray, use
+    QJsonArray::const_iterator instead. It is generally good practice to
+    use QJsonArray::const_iterator on a non-const QJsonArray as well, unless
+    you need to change the QJsonArray through the iterator. Const
+    iterators are slightly faster, and can improve code readability.
+
+    The default QJsonArray::iterator constructor creates an uninitialized
+    iterator. You must initialize it using a QJsonArray function like
+    QJsonArray::begin(), QJsonArray::end(), or QJsonArray::insert() before you can
+    start iterating.
+
+    Most QJsonArray functions accept an integer index rather than an
+    iterator. For that reason, iterators are rarely useful in
+    connection with QJsonArray. One place where STL-style iterators do
+    make sense is as arguments to \l{generic algorithms}.
+
+    Multiple iterators can be used on the same array. However, be
+    aware that any non-const function call performed on the QJsonArray
+    will render all existing iterators undefined.
+
+    \sa QJsonArray::const_iterator
+*/
+
+/*! \typedef QJsonArray::iterator::iterator_category
+
+  A synonym for \e {std::random_access_iterator_tag} indicating
+  this iterator is a random access iterator.
+*/
+
+/*! \typedef QJsonArray::iterator::difference_type
+
+    \internal
+*/
+
+/*! \typedef QJsonArray::iterator::value_type
+
+    \internal
+*/
+
+/*! \typedef QJsonArray::iterator::reference
+
+    \internal
+*/
+
+/*! \fn QJsonArray::iterator::iterator()
+
+    Constructs an uninitialized iterator.
+
+    Functions like operator*() and operator++() should not be called
+    on an uninitialized iterator. Use operator=() to assign a value
+    to it before using it.
+
+    \sa QJsonArray::begin() QJsonArray::end()
+*/
+
+/*! \fn QJsonArray::iterator::iterator(const iterator &other)
+
+    Constructs a copy of \a other.
+*/
+
+/*! \fn QJsonValueRef QJsonArray::iterator::operator*() const
+
+    Returns a modifiable reference to the current item.
+
+    You can change the value of an item by using operator*() 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.
+*/
+
+/*! \fn QJsonValueRef QJsonArray::iterator::operator[](int j) const
+
+    Returns a modifiable reference to the item at position *this +
+    \a{j}.
+
+    This function is provided to make QJsonArray iterators behave like C++
+    pointers.
+
+    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 operator+()
+*/
+
+/*!
+    \fn bool QJsonArray::iterator::operator==(const iterator &other) const
+    \fn bool QJsonArray::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 QJsonArray::iterator::operator!=(const iterator &other) const
+    \fn bool QJsonArray::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 bool QJsonArray::iterator::operator<(const iterator& other) const
+    \fn bool QJsonArray::iterator::operator<(const const_iterator& other) const
+
+    Returns true if the item pointed to by this iterator is less than
+    the item pointed to by the \a other iterator.
+*/
+
+/*!
+    \fn bool QJsonArray::iterator::operator<=(const iterator& other) const
+    \fn bool QJsonArray::iterator::operator<=(const const_iterator& other) const
+
+    Returns true if the item pointed to by this iterator is less than
+    or equal to the item pointed to by the \a other iterator.
+*/
+
+/*!
+    \fn bool QJsonArray::iterator::operator>(const iterator& other) const
+    \fn bool QJsonArray::iterator::operator>(const const_iterator& other) const
+
+    Returns true if the item pointed to by this iterator is greater
+    than the item pointed to by the \a other iterator.
+*/
+
+/*!
+    \fn bool QJsonArray::iterator::operator>=(const iterator& other) const
+    \fn bool QJsonArray::iterator::operator>=(const const_iterator& other) const
+
+    Returns true if the item pointed to by this iterator is greater
+    than or equal to the item pointed to by the \a other iterator.
+*/
+
+/*! \fn QJsonArray::iterator &QJsonArray::iterator::operator++()
+
+    The prefix ++ operator (\c{++it}) advances the iterator to the
+    next item in the array and returns an iterator to the new current
+    item.
+
+    Calling this function on QJsonArray::end() leads to undefined results.
+
+    \sa operator--()
+*/
+
+/*! \fn QJsonArray::iterator QJsonArray::iterator::operator++(int)
+
+    \overload
+
+    The postfix ++ operator (\c{it++}) advances the iterator to the
+    next item in the array and returns an iterator to the previously
+    current item.
+*/
+
+/*! \fn QJsonArray::iterator &QJsonArray::iterator::operator--()
+
+    The prefix -- operator (\c{--it}) makes the preceding item
+    current and returns an iterator to the new current item.
+
+    Calling this function on QJsonArray::begin() leads to undefined results.
+
+    \sa operator++()
+*/
+
+/*! \fn QJsonArray::iterator QJsonArray::iterator::operator--(int)
+
+    \overload
+
+    The postfix -- operator (\c{it--}) makes the preceding item
+    current and returns an iterator to the previously current item.
+*/
+
+/*! \fn QJsonArray::iterator &QJsonArray::iterator::operator+=(int j)
+
+    Advances the iterator by \a j items. (If \a j is negative, the
+    iterator goes backward.)
+
+    \sa operator-=(), operator+()
+*/
+
+/*! \fn QJsonArray::iterator &QJsonArray::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-()
+*/
+
+/*! \fn QJsonArray::iterator QJsonArray::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-(), operator+=()
+*/
+
+/*! \fn QJsonArray::iterator QJsonArray::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+(), operator-=()
+*/
+
+/*! \fn int QJsonArray::iterator::operator-(iterator other) const
+
+    Returns the number of items between the item pointed to by \a
+    other and the item pointed to by this iterator.
+*/
+
+/*! \class QJsonArray::const_iterator
+    \brief The QJsonArray::const_iterator class provides an STL-style const iterator for QJsonArray.
+
+    QJsonArray::const_iterator allows you to iterate over a
+    QJsonArray. If you want to modify the QJsonArray as
+    you iterate over it, use QJsonArray::iterator instead. It is generally
+    good practice to use QJsonArray::const_iterator on a non-const QJsonArray
+    as well, unless you need to change the QJsonArray through the
+    iterator. Const iterators are slightly faster, and can improve
+    code readability.
+
+    The default QJsonArray::const_iterator constructor creates an
+    uninitialized iterator. You must initialize it using a QJsonArray
+    function like QJsonArray::constBegin(), QJsonArray::constEnd(), or
+    QJsonArray::insert() before you can start iterating.
+
+    Most QJsonArray functions accept an integer index rather than an
+    iterator. For that reason, iterators are rarely useful in
+    connection with QJsonArray. One place where STL-style iterators do
+    make sense is as arguments to \l{generic algorithms}.
+
+    Multiple iterators can be used on the same array. However, be
+    aware that any non-const function call performed on the QJsonArray
+    will render all existing iterators undefined.
+
+    \sa QJsonArray::iterator, QJsonArrayIterator
+*/
+
+/*! \fn QJsonArray::const_iterator::const_iterator()
+
+    Constructs an uninitialized iterator.
+
+    Functions like operator*() and operator++() should not be called
+    on an uninitialized iterator. Use operator=() to assign a value
+    to it before using it.
+
+    \sa QJsonArray::constBegin() QJsonArray::constEnd()
+*/
+
+/*! \typedef QJsonArray::const_iterator::iterator_category
+
+  A synonym for \e {std::random_access_iterator_tag} indicating
+  this iterator is a random access iterator.
+*/
+
+/*! \typedef QJsonArray::const_iterator::difference_type
+
+    \internal
+*/
+
+/*! \typedef QJsonArray::const_iterator::value_type
+
+    \internal
+*/
+
+/*! \typedef QJsonArray::const_iterator::reference
+
+    \internal
+*/
+
+/*! \fn QJsonArray::const_iterator::const_iterator(const const_iterator &other)
+
+    Constructs a copy of \a other.
+*/
+
+/*! \fn QJsonArray::const_iterator::const_iterator(const iterator &other)
+
+    Constructs a copy of \a other.
+*/
+
+/*! \fn QJsonValue QJsonArray::const_iterator::operator*() const
+
+    Returns the current item.
+*/
+
+/*! \fn QJsonValue QJsonArray::const_iterator::operator[](int j) const
+
+    Returns the item at position *this + \a{j}.
+
+    This function is provided to make QJsonArray iterators behave like C++
+    pointers.
+
+    \sa operator+()
+*/
+
+/*! \fn bool QJsonArray::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 QJsonArray::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 bool QJsonArray::const_iterator::operator<(const const_iterator& other) const
+
+    Returns true if the item pointed to by this iterator is less than
+    the item pointed to by the \a other iterator.
+*/
+
+/*!
+    \fn bool QJsonArray::const_iterator::operator<=(const const_iterator& other) const
+
+    Returns true if the item pointed to by this iterator is less than
+    or equal to the item pointed to by the \a other iterator.
+*/
+
+/*!
+    \fn bool QJsonArray::const_iterator::operator>(const const_iterator& other) const
+
+    Returns true if the item pointed to by this iterator is greater
+    than the item pointed to by the \a other iterator.
+*/
+
+/*!
+    \fn bool QJsonArray::const_iterator::operator>=(const const_iterator& other) const
+
+    Returns true if the item pointed to by this iterator is greater
+    than or equal to the item pointed to by the \a other iterator.
+*/
+
+/*! \fn QJsonArray::const_iterator &QJsonArray::const_iterator::operator++()
+
+    The prefix ++ operator (\c{++it}) advances the iterator to the
+    next item in the array and returns an iterator to the new current
+    item.
+
+    Calling this function on QJsonArray::end() leads to undefined results.
+
+    \sa operator--()
+*/
+
+/*! \fn QJsonArray::const_iterator QJsonArray::const_iterator::operator++(int)
+
+    \overload
+
+    The postfix ++ operator (\c{it++}) advances the iterator to the
+    next item in the array and returns an iterator to the previously
+    current item.
+*/
+
+/*! \fn QJsonArray::const_iterator &QJsonArray::const_iterator::operator--()
+
+    The prefix -- operator (\c{--it}) makes the preceding item
+    current and returns an iterator to the new current item.
+
+    Calling this function on QJsonArray::begin() leads to undefined results.
+
+    \sa operator++()
+*/
+
+/*! \fn QJsonArray::const_iterator QJsonArray::const_iterator::operator--(int)
+
+    \overload
+
+    The postfix -- operator (\c{it--}) makes the preceding item
+    current and returns an iterator to the previously current item.
+*/
+
+/*! \fn QJsonArray::const_iterator &QJsonArray::const_iterator::operator+=(int j)
+
+    Advances the iterator by \a j items. (If \a j is negative, the
+    iterator goes backward.)
+
+    \sa operator-=(), operator+()
+*/
+
+/*! \fn QJsonArray::const_iterator &QJsonArray::const_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-()
+*/
+
+/*! \fn QJsonArray::const_iterator QJsonArray::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.)
+
+    \sa operator-(), operator+=()
+*/
+
+/*! \fn QJsonArray::const_iterator QJsonArray::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.)
+
+    \sa operator+(), operator-=()
+*/
+
+/*! \fn int QJsonArray::const_iterator::operator-(const_iterator other) const
+
+    Returns the number of items between the item pointed to by \a
+    other and the item pointed to by this iterator.
+*/
+
+
+/*!
+    \internal
+ */
 void QJsonArray::detach(uint reserve)
 {
     if (!d) {
@@ -300,6 +980,9 @@ void QJsonArray::detach(uint reserve)
     a = static_cast<Private::Array *>(d->header->root());
 }
 
+/*!
+    \internal
+ */
 void QJsonArray::compact() const
 {
     if (!d || !d->compactionCounter)