Documentation for QJsonValue

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

1 files changed, 199 insertions, 0 deletions

diff --git a/src/qjsonvalue.cpp b/src/qjsonvalue.cpp
index 0756e35..803f4fa 100644
--- a/src/qjsonvalue.cpp
+++ b/src/qjsonvalue.cpp
@@ -54,11 +54,51 @@ namespace QtJson {
 static const Private::Base emptyArray = { { qToLittleEndian(sizeof(Private::Base)) }, { 0 }, { 0 } };
 static const Private::Base emptyObject = { { qToLittleEndian(sizeof(Private::Base)) }, { 0 }, { 0 } };
 
+/*!
+    \class QJsonValue
+    \ingroup json
+    \reentrant
+    \since 5.0
+
+    \brief The QJsonValue class encapsulates a value in JSON.
+
+    A value in JSON can be one of 6 basic types:
+
+    JSON is a format to store structured data. It has 6 basic data types:
+
+    \list
+    \o bool QJsonValue::Bool
+    \o double QJsonValue::Number
+    \o string QJsonValue::String
+    \o array QJsonValue::Array
+    \o object QJsonValue::Object
+    \o null QJsonValue::Null
+    \endlist
+
+    A value can represent any of the above data types. In addition, QJsonValue has one special
+    flag to represent undefined values. This can be queried with isUndefined().
+
+    The type of the value can be queried with type() or accessors like isBool(), isString(), etc.
+    The value can be converted to the type stored in it using the toBool(), toString(), etc. methods.
+
+    Values are strictly typed internally and contrary to QVariant will not attempt to do any implicit type
+    conversions. This implies that converting to a type that is not stored in the value will return a default
+    constructed return value.
+*/
+
+/*!
+    Creates a QJsonValue of type \a type.
+
+    The default is to create a Null value.
+ */
 QJsonValue::QJsonValue(Type type)
     : t(type), d(0), dbl(0.)
 {
 }
 
+/*!
+    \internal
+ */
 QJsonValue::QJsonValue(Private::Data *data, Private::Base *base, const Private::Value &v)
     : d(0)
 {
@@ -90,24 +130,37 @@ QJsonValue::QJsonValue(Private::Data *data, Private::Base *base, const Private::
         d->ref.ref();
 }
 
+/*!
+    Creates a value of type Bool, with value \a b.
+ */
 QJsonValue::QJsonValue(bool b)
     : t(Bool), d(0)
 {
     this->b = b;
 }
 
+/*!
+    Creates a value of type Number, with value \a n.
+ */
 QJsonValue::QJsonValue(double n)
     : t(Number), d(0)
 {
     this->dbl = n;
 }
 
+/*!
+    \overload
+    Creates a value of type Number, with value \a n.
+ */
 QJsonValue::QJsonValue(int n)
     : t(Number), d(0)
 {
     this->dbl = n;
 }
 
+/*!
+    Creates a value of type String, with value \a s.
+ */
 QJsonValue::QJsonValue(const QString &s)
     : t(String), d(0)
 {
@@ -115,6 +168,9 @@ QJsonValue::QJsonValue(const QString &s)
     stringData->ref.ref();
 }
 
+/*!
+    Creates a value of type String, with value \a s.
+ */
 QJsonValue::QJsonValue(const QLatin1String &s)
     : t(String), d(0)
 {
@@ -124,6 +180,9 @@ QJsonValue::QJsonValue(const QLatin1String &s)
     stringData->ref.ref();
 }
 
+/*!
+    Creates a value of type Array, with value \a a.
+ */
 QJsonValue::QJsonValue(const QJsonArray &a)
     : t(Array), d(a.d)
 {
@@ -133,6 +192,9 @@ QJsonValue::QJsonValue(const QJsonArray &a)
         d->ref.ref();
 }
 
+/*!
+    Creates a value of type Object, with value \a o.
+ */
 QJsonValue::QJsonValue(const QJsonObject &o)
     : t(Object), d(o.d)
 {
@@ -143,6 +205,9 @@ QJsonValue::QJsonValue(const QJsonObject &o)
 }
 
 
+/*!
+    Destroys the value.
+ */
 QJsonValue::~QJsonValue()
 {
     if (t == String && stringData && !stringData->ref.deref())
@@ -152,6 +217,9 @@ QJsonValue::~QJsonValue()
         delete d;
 }
 
+/*!
+    Creates a copy of \a other.
+ */
 QJsonValue::QJsonValue(const QJsonValue &other)
 {
     t = other.t;
@@ -164,6 +232,9 @@ QJsonValue::QJsonValue(const QJsonValue &other)
         stringData->ref.ref();
 }
 
+/*!
+    Assigns the value stored in \a other to this object.
+ */
 QJsonValue &QJsonValue::operator =(const QJsonValue &other)
 {
     if (t == String && stringData && !stringData->ref.deref())
@@ -188,6 +259,29 @@ QJsonValue &QJsonValue::operator =(const QJsonValue &other)
     return *this;
 }
 
+/*!
+    Converts \a variant to a QJsonValue and returns it.
+
+    The conversion will convert QVariant types as follows:
+
+    \list
+    \o QVariant::Bool to Bool
+    \o QVariant::Int
+    \o QVariant::Double
+    \o QVariant::LongLong
+    \o QVariant::ULongLong
+    \o QVariant::UInt to Number
+    \o QVariant::String to String
+    \o QVariant::StringList
+    \o QVariant::VariantList to Array
+    \o QVariant::VariantMap to Object
+    \endlist
+
+    For all other QVariant types a conversion to a QString will be attempted. If the returned string
+    is empty, a Null QJsonValue will be stored, otherwise a String value using the returned QString.
+
+    \sa toVariant()
+ */
 QJsonValue QJsonValue::fromVariant(const QVariant &variant)
 {
     switch (variant.type()) {
@@ -217,6 +311,21 @@ QJsonValue QJsonValue::fromVariant(const QVariant &variant)
     return QJsonValue(string);
 }
 
+/*!
+    Converts the value to a QVariant.
+
+    The QJsonValue types will be converted as follows:
+
+    \value Null     QVariant()
+    \value Bool     QVariant::Bool
+    \value Number   QVariant::Double
+    \value String   QVariant::String
+    \value Array    QVariantList
+    \value Object   QVariantMap
+    \value Undefined QVariant()
+
+    \sa fromVariant()
+ */
 QVariant QJsonValue::toVariant() const
 {
     switch (t) {
@@ -237,12 +346,37 @@ QVariant QJsonValue::toVariant() const
     return QVariant();
 }
 
+/*!
+    \enum QJsonValue::Type
 
+    This enum describes the type of the JSON value.
+
+    \value Null     A Null value
+    \value Bool     A boolean value. Use toBool() to convert to a bool.
+    \value Number   A number. Use toNumber() to convert to a double.
+    \value String   A string. Use toString() to convert to a QString.
+    \value Array    An array. Use toArray() to convert to a QJsonArray.
+    \value Object   An object. Use toObject() to convert to a QJsonObject.
+    \value Undefined The value is undefined. This is usually returned as an
+                    error condition, when trying to read an out of bounds value
+                    in an array or a non existant key in an object.
+*/
+
+/*!
+    Returns the type of the value.
+
+    \sa QJsonValue::Type
+ */
 QJsonValue::Type QJsonValue::type() const
 {
     return t;
 }
 
+/*!
+    Converts the value to a bool and returns it.
+
+    If type() is not bool, false will be returned.
+ */
 bool QJsonValue::toBool() const
 {
     if (t != Bool)
@@ -250,6 +384,11 @@ bool QJsonValue::toBool() const
     return b;
 }
 
+/*!
+    Converts the value to a double and returns it.
+
+    If type() is not Number, 0. will be returned.
+ */
 double QJsonValue::toNumber() const
 {
     if (t != Number)
@@ -257,6 +396,11 @@ double QJsonValue::toNumber() const
     return dbl;
 }
 
+/*!
+    Converts the value to an int and returns it.
+
+    If type() is not Number, 0. will be returned.
+ */
 int QJsonValue::toInt() const
 {
     if (t != Number)
@@ -264,6 +408,11 @@ int QJsonValue::toInt() const
     return (int)dbl;
 }
 
+/*!
+    Converts the value to a QString and returns it.
+
+    If type() is not String, a QString() will be returned.
+ */
 QString QJsonValue::toString() const
 {
     if (t != String)
@@ -272,6 +421,11 @@ QString QJsonValue::toString() const
     return QString(*(const QConstStringData<1> *)stringData);
 }
 
+/*!
+    Converts the value to an array and returns it.
+
+    If type() is not Array, a QJsonArray() will be returned.
+ */
 QJsonArray QJsonValue::toArray() const
 {
     if (!d || t != Array)
@@ -280,6 +434,11 @@ QJsonArray QJsonValue::toArray() const
     return QJsonArray(d, array);
 }
 
+/*!
+    Converts the value to an object and returns it.
+
+    If type() is not Object, a QJsonObject() will be returned.
+ */
 QJsonObject QJsonValue::toObject() const
 {
     if (!d || t != Object)
@@ -288,6 +447,9 @@ QJsonObject QJsonValue::toObject() const
     return QJsonObject(d, object);
 }
 
+/*!
+    Returns true if the value is equal to \a other.
+ */
 bool QJsonValue::operator==(const QJsonValue &other) const
 {
     if (t != other.t)
@@ -311,11 +473,17 @@ bool QJsonValue::operator==(const QJsonValue &other) const
     return true;
 }
 
+/*!
+    Returns true if the value is not equal to \a other.
+ */
 bool QJsonValue::operator!=(const QJsonValue &other) const
 {
     return !(*this == other);
 }
 
+/*!
+    \internal
+ */
 void QJsonValue::detach()
 {
     if (!d)
@@ -329,6 +497,9 @@ void QJsonValue::detach()
     object = static_cast<Private::Object *>(d->header->root());
 }
 
+/*!
+    \internal
+ */
 int QJsonValue::requiredStorage(bool *compressed) const
 {
     *compressed = false;
@@ -355,6 +526,9 @@ int QJsonValue::requiredStorage(bool *compressed) const
     return 0;
 }
 
+/*!
+    \internal
+ */
 uint QJsonValue::valueToStore(uint offset) const
 {
     switch (t) {
@@ -376,6 +550,9 @@ uint QJsonValue::valueToStore(uint offset) const
     return 0;
 }
 
+/*!
+    \internal
+ */
 void QJsonValue::copyData(char *dest, bool compressed) const
 {
     switch (t) {
@@ -402,6 +579,28 @@ void QJsonValue::copyData(char *dest, bool compressed) const
     }
 }
 
+/*!
+    \class QJsonValueRef
+    \reentrant
+    \brief The QJsonValueRef class is a helper class for QJsonValue.
+
+    \internal
+
+    \ingroup json
+
+    When you get an object of type QJsonValueRef, if you can assign to it,
+    the assignment will apply to the character in the string from
+    which you got the reference. That is its whole purpose in life.
+
+    You can use it exactly in the same way as a reference to a QJsonValue.
+
+    The QJsonValueRef becomes invalid once modifications are made to the
+    string: if you want to keep the character, copy it into a QJsonValue.
+
+    Most of the QJsonValue member functions also exist in QJsonValueRef.
+    However, they are not explicitly documented here.
+*/
+
 
 QJsonValueRef &QJsonValueRef::operator =(const QJsonValue &val)
 {