Documentation for QJsonDocument

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

2 files changed, 184 insertions, 4 deletions

diff --git a/src/qjsondocument.cpp b/src/qjsondocument.cpp
index 6e0c1c4..5736ab0 100644
--- a/src/qjsondocument.cpp
+++ b/src/qjsondocument.cpp
@@ -50,23 +50,62 @@
 
 namespace QtJson {
 
+/*! \class QJsonDocument
+    \ingroup json
+    \reentrant
+    \since 5.0
+
+    \brief The QJsonDocument class provides a way to read and write JSON documents.
+
+    QJsonDocument is a class that wraps a complete JSON document and can read and
+    write this document both from a utf-8 encoded text based representation as well
+    as Qt's own binary format.
+
+    A JSON document can be converted from it's text based representation to a QJsonDocument
+    using QJsonDocument::fromJson(). toJson() converts it back to text. The parser is very
+    fast and efficient and converts the JSON to the binary representation used by Qt.
+
+    Validity of the parsed document can be queried with isValid()
+
+    A document can be queried as to whether it contains an array or an object using isArray()
+    and isObject(). The array or object contained in the document can be retrieved using
+    array() or object() and then read or manipulated.
+
+    A document can also be created from a stored binary representation using fromBinaryData() or
+    fromRawData(). In this case the document is not automatically checked for validity. If the
+    document comes from an untrusted source isValid() should therefore be called before using
+    the document any further. isValid() will guarantee that the binary document is in a state
+    that will not cause problems when using it.
+*/
+
+/*!
+ * Constructs an empty and invalid document.
+ */
 QJsonDocument::QJsonDocument()
     : d(0)
 {
 }
 
+/*!
+ * Creates a QJsonDocument from \a object.
+ */
 QJsonDocument::QJsonDocument(const QJsonObject &object)
     : d(0)
 {
     setObject(object);
 }
 
+/*!
+ * Constructs a QJsonDocument from \a array.
+ */
 QJsonDocument::QJsonDocument(const QJsonArray &array)
     : d(0)
 {
     setArray(array);
 }
 
+/*! \internal
+ */
 QJsonDocument::QJsonDocument(Private::Data *data)
     : d(data)
 {
@@ -74,13 +113,18 @@ QJsonDocument::QJsonDocument(Private::Data *data)
     d->ref.ref();
 }
 
-
+/*!
+ * Deletes the document.
+ */
 QJsonDocument::~QJsonDocument()
 {
     if (d && !d->ref.deref())
         delete d;
 }
 
+/*!
+ * Creates a copy of the \a other document.
+ */
 QJsonDocument::QJsonDocument(const QJsonDocument &other)
 {
     d = other.d;
@@ -88,6 +132,10 @@ QJsonDocument::QJsonDocument(const QJsonDocument &other)
         d->ref.ref();
 }
 
+/*!
+ * Assigns the \a other document to this QJsonDocument.
+ * \returns a reference to this object.
+ */
 QJsonDocument &QJsonDocument::operator =(const QJsonDocument &other)
 {
     if (d != other.d) {
@@ -101,6 +149,20 @@ QJsonDocument &QJsonDocument::operator =(const QJsonDocument &other)
     return *this;
 }
 
+/*!
+ Creates a QJsonDocument that uses the first \a size bytes from
+ \a data. It assumes \a data contains a binary encoded JSON document.
+ The created document does not take ownership of \a data and the caller
+ has to guarantee that \a data will not be deleted or modified as long as
+ any QJsonDocument, QJsonObject or QJsonArray still references the data.
+
+ No validity checks on \a data are performed. If you are unsure about
+ the validity of the binary data, call isValid
+
+ \returns a QJsonDocument representing the data
+
+ \sa rawData fromBinaryData isValid
+ */
 QJsonDocument QJsonDocument::fromRawData(const char *data, int size)
 {
     Private::Data *d = new Private::Data((char *)data, size);
@@ -108,6 +170,13 @@ QJsonDocument QJsonDocument::fromRawData(const char *data, int size)
     return QJsonDocument(d);
 }
 
+/*!
+  \returns the raw binary representation of the data
+  \a size will contain the size of the \a data.
+
+  This method is useful to e.g. stream the JSON document
+  in it's binary form to a file.
+ */
 const char *QJsonDocument::rawData(int *size) const
 {
     if (!d) {
@@ -118,6 +187,13 @@ const char *QJsonDocument::rawData(int *size) const
     return d->rawData;
 }
 
+/*!
+ Creates a QJsonDocument from \a data. The data is expected to
+ be valid, call isValid() if the data comes from an untrusted
+ source before using it.
+
+ \sa toBinaryData fromRawData isValid
+ */
 QJsonDocument QJsonDocument::fromBinaryData(const QByteArray &data)
 {
     Private::Header *h = (Private::Header *) data.constData();
@@ -134,7 +210,16 @@ QJsonDocument QJsonDocument::fromBinaryData(const QByteArray &data)
     return QJsonDocument(d);
 }
 
-QJsonDocument QJsonDocument::fromVariant(const QVariant &v)
+/*!
+ Creates a QJsonDocument from the the QVariant \a variant.
+
+ If the \a variant contains any other type than a QVariant::Map,
+ QVariant::List or QVariant::StringList, the returned document
+ document is invalid.
+
+ \sa toVariant
+ */
+QJsonDocument QJsonDocument::fromVariant(const QVariant &variant)
 {
     QJsonDocument doc;
     if (v.type() == QVariant::Map) {
@@ -147,6 +232,22 @@ QJsonDocument QJsonDocument::fromVariant(const QVariant &v)
     return doc;
 }
 
+/*!
+ \returns a QVariant representing the Json document.
+
+ The JSON data types are mappes as follows:
+
+ \list
+ \o Null an empty variant
+ \o Bool QVariant::Bool
+ \o Number QVariant::Double
+ \o String QVariant::String
+ \o Array QVariant::List
+ \o Object QVariant::Map
+ \endlist
+
+ \sa fromVariant.
+ */
 QVariant QJsonDocument::toVariant() const
 {
     if (!d)
@@ -158,6 +259,11 @@ QVariant QJsonDocument::toVariant() const
         return QJsonObject(d, static_cast<Private::Object *>(d->header->root())).toVariantMap();
 }
 
+/*!
+ Converts the QJsonDocument to a utf-8 encoded JSON document.
+
+ \sa fromJson
+ */
 QByteArray QJsonDocument::toJson() const
 {
     if (!d)
@@ -173,12 +279,22 @@ QByteArray QJsonDocument::toJson() const
     return json;
 }
 
+/*!
+ Parses a utf-8 encoded JSON document and creates a QJsonDocument
+ from it. isValid will return true if no error was encountered during
+ parsing.
+
+ \sa toJson
+ */
 QJsonDocument QJsonDocument::fromJson(const QByteArray &json)
 {
     QJsonParser parser(json.constData(), json.length());
     return parser.parse();
 }
 
+/*!
+    \returns true if the document doesn't contain any data.
+ */
 bool QJsonDocument::isEmpty() const
 {
     if (!d)
@@ -187,6 +303,18 @@ bool QJsonDocument::isEmpty() const
     return false;
 }
 
+/*!
+ \returns a binary representation of the document.
+
+ The binary representation is also the native format used internally in Qt,
+ and such very efficient and fast to convert to and from.
+
+ The binary format can be stored on disk and interchanged with other applications
+ or computers. fromBinaryData() can be used to convert it back into a
+ JSON document.
+
+ \sa fromBinaryData
+ */
 QByteArray QJsonDocument::toBinaryData() const
 {
     if (!d || !d->rawData)
@@ -195,6 +323,11 @@ QByteArray QJsonDocument::toBinaryData() const
     return QByteArray(d->rawData, d->header->root()->size + sizeof(Private::Header));
 }
 
+/*!
+    \returns true if the document contains an array.
+
+    \sa array() isObject()
+ */
 bool QJsonDocument::isArray() const
 {
     if (!d)
@@ -204,6 +337,11 @@ bool QJsonDocument::isArray() const
     return h->root()->isArray();
 }
 
+/*!
+    \returns true if the document contains an object.
+
+    \sa object() isArray()
+ */
 bool QJsonDocument::isObject() const
 {
     if (!d)
@@ -213,6 +351,14 @@ bool QJsonDocument::isObject() const
     return h->root()->isObject();
 }
 
+/*!
+    \returns the QJsonObject contained in the document.
+
+    Returns an empty object if the document contains an
+    array.
+
+    \sa isObject array setObject
+ */
 QJsonObject QJsonDocument::object() const
 {
     if (d) {
@@ -223,6 +369,14 @@ QJsonObject QJsonDocument::object() const
     return QJsonObject();
 }
 
+/*!
+    \returns the QJsonArray contained in the document.
+
+    Returns an empty array if the document contains an
+    object.
+
+    \sa isArray object setArray
+ */
 QJsonArray QJsonDocument::array() const
 {
     if (d) {
@@ -233,6 +387,11 @@ QJsonArray QJsonDocument::array() const
     return QJsonArray();
 }
 
+/*!
+    Sets \a object as the main object of this document.
+
+    \sa setArray object
+ */
 void QJsonDocument::setObject(const QJsonObject &object)
 {
     if (d && !d->ref.deref())
@@ -255,6 +414,11 @@ void QJsonDocument::setObject(const QJsonObject &object)
     d->ref.ref();
 }
 
+/*!
+    Sets \a array as the main object of this document.
+
+    \sa setObject array
+ */
 void QJsonDocument::setArray(const QJsonArray &array)
 {
     if (d && !d->ref.deref())
@@ -277,7 +441,9 @@ void QJsonDocument::setArray(const QJsonArray &array)
     d->ref.ref();
 }
 
-
+/*!
+    returns true if \a other is equal to this document
+ */
 bool QJsonDocument::operator==(const QJsonDocument &other) const
 {
     if (d == other.d)
@@ -297,11 +463,25 @@ bool QJsonDocument::operator==(const QJsonDocument &other) const
                 == QJsonArray(other.d, static_cast<Private::Array *>(other.d->header->root()));
 }
 
+/*!
+    returns true if \a other is not equal to this document
+ */
 bool QJsonDocument::operator!=(const QJsonDocument &other) const
 {
     return !(*this == other);
 }
 
+/*!
+    returns true if this document is valid.
+
+    Documents created from utf-8 encoded text are validated during
+    parsing.
+
+    Documents created from binary data are however not validated, and
+    an explicit call to isValid is required to perform the validation.
+    This allow for optimised access to documents that are stored in binary
+    format and originate from trusted sources.
+ */
 bool QJsonDocument::isValid()
 {
     if (!d)
diff --git a/src/qjsondocument.h b/src/qjsondocument.h
index 65847f6..e29d107 100644
--- a/src/qjsondocument.h
+++ b/src/qjsondocument.h
@@ -71,7 +71,7 @@ public:
     static QJsonDocument fromBinaryData(const QByteArray &data);
     QByteArray toBinaryData() const;
 
-    static QJsonDocument fromVariant(const QVariant &v);
+    static QJsonDocument fromVariant(const QVariant &variant);
     QVariant toVariant() const;
 
     QByteArray toJson() const;