15 files changed, 154 insertions, 0 deletions

diff --git a/src/corelib/doc/src/qtserialization.qdoc b/src/corelib/doc/src/qtserialization.qdoc
new file mode 100644
index 0000000000..dfceed55f2
--- /dev/null
+++ b/src/corelib/doc/src/qtserialization.qdoc
@@ -0,0 +1,138 @@
+// Copyright (C) 2022 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+    \page qtserialization.html
+    \title Qt Serialization
+    \brief Serializations provided by Qt API
+
+    The purpose of serialization is to save the state of an object to be able to
+    recreate it when needed. It allows you to perform actions like:
+
+    \list
+        \li Sending the object to a remote application by using a web service
+        \li Passing the object as a JSON or XML string
+        \li Saving and restoring user information or sharing it across applications
+    \endlist
+
+    The Qt API provides support for serialization for several use cases:
+
+    \list
+    \li \l JSON support in Qt provides an easy to use C++ API to parse, modify
+           and save JSON data. \l {CBOR} {CBOR Support in Qt} is a compact form
+           of binary data encoding that is a superset of JSON.
+    \li \l QDataStream provides serialization of binary data to a QIODevice
+    \li \l {Qt XML C++ Classes} provide C++ implementations of the \l XML Streaming
+           and DOM standards for XML
+    \li \l CBOR is Qt's implementation for the CBOR serialization format.
+    \li \l QSettings provides a way of serializing and storing platform independent
+           application settings.
+    \endlist
+
+    \section1 Advantages of JSON and CBOR
+
+    When you use \l JSON information is stored in a QJsonObject and a QJsonDocument
+    takes care to stream values into a QByteArray.
+
+    For example
+    \code
+        QJsonObject jobject;
+        jobject["SensorID"] = m_id;
+        jobject["AmbientTemperature"] = m_ambientTemperature;
+        jobject["ObjectTemperature"] = m_objectTemperature;
+        jobject["AccelerometerX"] = m_accelerometerX;
+        jobject["AccelerometerY"] = m_accelerometerY;
+        jobject["AccelerometerZ"] = m_accelerometerZ;
+        jobject["Altitude"] = m_altitude;
+        jobject["Light"] = m_light;
+        jobject["Humidity"] = m_humidity;
+        QJsonDocument doc( jobject );
+
+        return doc.toJson();
+    \endcode
+
+    JSON has several advantages:
+
+    \list
+    \li Textual JSON is declarative, which makes it readable to humans
+    \li The information is structured
+    \li Exchanging generic information is easy
+    \li JSON allows extending messages with additional values
+    \li Many solutions exist to receive and parse JSON in cloud-based solutions
+    \endlist
+
+    \l CBOR is the Concise Binary Object Representation, a very compact form of
+    binary data encoding that is a superset of JSON. It was created by the IETF
+    Constrained RESTful Environments (CoRE) WG, which has been used in many new
+    RFCs. CBOR shares many of the advantages of JSON, but sacrifices human
+    readability for compactness.
+
+    \section1 Advantages of QDataStream Classes
+
+    \l QDataStream is a viable option when the whole flow of data is determined
+    and not about to change. In addition, both the reader and the writer of the
+    data must be written in Qt.
+
+    Adding support for this to a class requires two additional operators.
+    For example, for a class named SensorInformation:
+
+    \code
+    QDataStream &operator<<(QDataStream &, const SensorInformation &);
+    QDataStream &operator>>(QDataStream &, SensorInformation &);
+    \endcode
+
+    The implementation for the serialization is shown below:
+
+    \code
+    QDataStream &operator<<(QDataStream &out, const SensorInformation &item)
+    {
+        QDataStream::FloatingPointPrecision prev = out.floatingPointPrecision();
+        out.setFloatingPointPrecision(QDataStream::DoublePrecision);
+        out << item.m_id
+            << item.m_ambientTemperature
+            << item.m_objectTemperature
+            << item.m_accelerometerX
+            << item.m_accelerometerY
+            << item.m_accelerometerZ
+            << item.m_altitude
+            << item.m_light
+            << item.m_humidity;
+        out.setFloatingPointPrecision(prev);
+        return out;
+    }
+    \endcode
+
+    Deserialization works similarly, but using the \c {>>} operator.
+    For example, \c {out >> item.m_id}, and so on.
+
+    Usually, using QDataStream is faster than using textual JSON.
+
+    \section1 Advantages of Qt XML C++ Classes
+
+    Qt provides the QDomDocument class that represents the XML document and
+    two classes for reading and writing the XML through a simple streaming API:
+    QXmlStreamReader and QXmlStreamWriter.
+
+    QDomDocument class represents the entire XML document. It is the root of the
+    document tree and provides primary access to the document's data.
+
+    A stream reader reports an XML document as a stream of tokens. This differs
+    from SAX as SAX applications provide handlers to receive XML events from the
+    parser, whereas the QXmlStreamReader drives the loop, pulling tokens from the
+    reader when they are needed. This pulling approach makes it possible to build
+    recursive descent parsers, allowing XML parsing code to be split into
+    different methods or classes.
+
+    QXmlStreamReader a parser for well-formed XML 1.0, excluding external parsed
+    entities. Hence, data provided to the stream reader adheres to the
+    W3C's criteria for well-formed XML, or an error will be raised. Functions
+    such as \c atEnd(), \c error(), and \c hasError() can be used to test  for
+    such errors and obtain a description of them.
+
+    The QXmlStreamWriter is a streaming API that takes care of prefixing namespaces,
+    when the namespaceUri is specified when writing elements or attributes.
+
+    \section1 Classes that provide serialization
+
+    \annotatedlist qtserialization
+*/
diff --git a/src/corelib/serialization/qcborarray.cpp b/src/corelib/serialization/qcborarray.cpp
index 95fd47b767..dc373533c5 100644
--- a/src/corelib/serialization/qcborarray.cpp
+++ b/src/corelib/serialization/qcborarray.cpp
@@ -13,6 +13,7 @@ using namespace QtCbor;
     \class QCborArray
     \inmodule QtCore
     \ingroup cbor
+    \ingroup qtserialization
     \reentrant
     \since 5.12
 
diff --git a/src/corelib/serialization/qcborcommon.cpp b/src/corelib/serialization/qcborcommon.cpp
index 844bcef4af..66d6dcd685 100644
--- a/src/corelib/serialization/qcborcommon.cpp
+++ b/src/corelib/serialization/qcborcommon.cpp
@@ -17,6 +17,7 @@ QT_IMPL_METATYPE_EXTERN(QCborTag)
 /*!
    \headerfile <QtCborCommon>
    \inmodule QtCore
+   \ingroup qtserialization
    \brief The <QtCborCommon> header contains definitions common to both the
    streaming classes (QCborStreamReader and QCborStreamWriter) and to
    QCborValue.
diff --git a/src/corelib/serialization/qcbormap.cpp b/src/corelib/serialization/qcbormap.cpp
index c8895cb42a..3b16c309b0 100644
--- a/src/corelib/serialization/qcbormap.cpp
+++ b/src/corelib/serialization/qcbormap.cpp
@@ -12,6 +12,7 @@ using namespace QtCbor;
     \class QCborMap
     \inmodule QtCore
     \ingroup cbor
+    \ingroup qtserialization
     \reentrant
     \since 5.12
 
diff --git a/src/corelib/serialization/qcborstreamreader.cpp b/src/corelib/serialization/qcborstreamreader.cpp
index 86fb1f0d7e..887bcdd6b0 100644
--- a/src/corelib/serialization/qcborstreamreader.cpp
+++ b/src/corelib/serialization/qcborstreamreader.cpp
@@ -60,6 +60,7 @@ static_assert(int(QCborStreamReader::Invalid) == CborInvalidType);
    \class QCborStreamReader
    \inmodule QtCore
    \ingroup cbor
+   \ingroup qtserialization
    \reentrant
    \since 5.12
 
diff --git a/src/corelib/serialization/qcborstreamwriter.cpp b/src/corelib/serialization/qcborstreamwriter.cpp
index a2ddc15161..e798da7e52 100644
--- a/src/corelib/serialization/qcborstreamwriter.cpp
+++ b/src/corelib/serialization/qcborstreamwriter.cpp
@@ -43,6 +43,7 @@ Q_DECLARE_TYPEINFO(CborEncoder, Q_PRIMITIVE_TYPE);
    \class QCborStreamWriter
    \inmodule QtCore
    \ingroup cbor
+   \ingroup qtserialization
    \reentrant
    \since 5.12
 
diff --git a/src/corelib/serialization/qcborvalue.cpp b/src/corelib/serialization/qcborvalue.cpp
index 1cb351906c..e9b351166f 100644
--- a/src/corelib/serialization/qcborvalue.cpp
+++ b/src/corelib/serialization/qcborvalue.cpp
@@ -44,6 +44,7 @@ Q_DECL_UNUSED static constexpr quint64 MaximumPreallocatedElementCount =
     \class QCborValue
     \inmodule QtCore
     \ingroup cbor
+    \ingroup qtserialization
     \reentrant
     \since 5.12
 
diff --git a/src/corelib/serialization/qdatastream.cpp b/src/corelib/serialization/qdatastream.cpp
index 34f8f7b5ff..ef404250b7 100644
--- a/src/corelib/serialization/qdatastream.cpp
+++ b/src/corelib/serialization/qdatastream.cpp
@@ -18,6 +18,7 @@ QT_BEGIN_NAMESPACE
 /*!
     \class QDataStream
     \inmodule QtCore
+    \ingroup qtserialization
     \reentrant
     \brief The QDataStream class provides serialization of binary data
     to a QIODevice.
diff --git a/src/corelib/serialization/qjsonarray.cpp b/src/corelib/serialization/qjsonarray.cpp
index 01899aaf95..96947cf2d0 100644
--- a/src/corelib/serialization/qjsonarray.cpp
+++ b/src/corelib/serialization/qjsonarray.cpp
@@ -22,6 +22,7 @@ QT_BEGIN_NAMESPACE
     \inmodule QtCore
     \ingroup json
     \ingroup shared
+    \ingroup qtserialization
     \reentrant
     \since 5.0
 
diff --git a/src/corelib/serialization/qjsondocument.cpp b/src/corelib/serialization/qjsondocument.cpp
index 01df13d097..1ba4b5952c 100644
--- a/src/corelib/serialization/qjsondocument.cpp
+++ b/src/corelib/serialization/qjsondocument.cpp
@@ -24,6 +24,7 @@ QT_BEGIN_NAMESPACE
     \inmodule QtCore
     \ingroup json
     \ingroup shared
+    \ingroup qtserialization
     \reentrant
     \since 5.0
 
diff --git a/src/corelib/serialization/qjsonobject.cpp b/src/corelib/serialization/qjsonobject.cpp
index ab482876af..d4f702e46e 100644
--- a/src/corelib/serialization/qjsonobject.cpp
+++ b/src/corelib/serialization/qjsonobject.cpp
@@ -25,6 +25,7 @@ QT_BEGIN_NAMESPACE
     \inmodule QtCore
     \ingroup json
     \ingroup shared
+    \ingroup qtserialization
     \reentrant
     \since 5.0
 
diff --git a/src/corelib/serialization/qjsonparser.cpp b/src/corelib/serialization/qjsonparser.cpp
index acc2bc383f..b11ae3a9d2 100644
--- a/src/corelib/serialization/qjsonparser.cpp
+++ b/src/corelib/serialization/qjsonparser.cpp
@@ -50,6 +50,7 @@ QT_BEGIN_NAMESPACE
     \inmodule QtCore
     \ingroup json
     \ingroup shared
+    \ingroup qtserialization
     \reentrant
     \since 5.0
 
diff --git a/src/corelib/serialization/qjsonvalue.cpp b/src/corelib/serialization/qjsonvalue.cpp
index 49fc0d85d1..cc15f412f4 100644
--- a/src/corelib/serialization/qjsonvalue.cpp
+++ b/src/corelib/serialization/qjsonvalue.cpp
@@ -53,6 +53,7 @@ static QJsonValue::Type convertFromCborType(QCborValue::Type type) noexcept
     \inmodule QtCore
     \ingroup json
     \ingroup shared
+    \ingroup qtserialization
     \reentrant
     \since 5.0
 
diff --git a/src/corelib/serialization/qtextstream.cpp b/src/corelib/serialization/qtextstream.cpp
index 2a2536aeee..a268002dc6 100644
--- a/src/corelib/serialization/qtextstream.cpp
+++ b/src/corelib/serialization/qtextstream.cpp
@@ -14,6 +14,7 @@ static const int QTEXTSTREAM_BUFFERSIZE = 16384;
 
     \ingroup io
     \ingroup string-processing
+    \ingroup qtserialization
     \reentrant
 
     QTextStream can operate on a QIODevice, a QByteArray or a
diff --git a/src/corelib/serialization/qxmlstream.cpp b/src/corelib/serialization/qxmlstream.cpp
index 80eed02b11..ed34c3e0d6 100644
--- a/src/corelib/serialization/qxmlstream.cpp
+++ b/src/corelib/serialization/qxmlstream.cpp
@@ -231,6 +231,8 @@ QXmlStreamEntityResolver *QXmlStreamReader::entityResolver() const
 
   \ingroup xml-tools
 
+  \ingroup qtserialization
+
   QXmlStreamReader provides a simple streaming API to parse well-formed
   XML. It is an alternative to first loading the complete XML into a
   DOM tree (see \l QDomDocument). QXmlStreamReader reads data either
@@ -2728,6 +2730,7 @@ QStringView QXmlStreamReader::documentEncoding() const
   simple streaming API.
 
   \ingroup xml-tools
+  \ingroup qtserialization
 
   QXmlStreamWriter is the counterpart to QXmlStreamReader for writing
   XML. Like its related class, it operates on a QIODevice specified