Add CBOR documentation

Add documentation of usage of CBOR in convert and cbordump examples,
add a CBOR overview, and add links to them other places in the
documentation.

Task-number: QTBUG-85912
Change-Id: I518792db63647bf9ddd4507d8d4b7ef056192f82
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>

7 files changed, 145 insertions, 5 deletions

diff --git a/examples/corelib/serialization/cbordump/doc/images/cbordump.png b/examples/corelib/serialization/cbordump/doc/images/cbordump.png
new file mode 100644
index 0000000000..72232c1a95
--- /dev/null
+++ b/examples/corelib/serialization/cbordump/doc/images/cbordump.png
diff --git a/examples/corelib/serialization/cbordump/doc/src/cbordump.qdoc b/examples/corelib/serialization/cbordump/doc/src/cbordump.qdoc
new file mode 100644
index 0000000000..c3565e184d
--- /dev/null
+++ b/examples/corelib/serialization/cbordump/doc/src/cbordump.qdoc
@@ -0,0 +1,52 @@
+// Copyright (C) 2022 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+    \example serialization/cbordump
+    \title Cbordump Example
+
+    \brief The Cbordump example demonstrates how to parse files in CBOR-format.
+
+    The Cbordump example reads from files or stdin content in CBOR-format and
+    dumps the decoded content to stdout. The cbordump utility can output in
+    CBOR diagnostic notation (which is similar to JSON), or it can have a
+    verbose output where each byte input is displayed with the encoding beside
+    it. This example shows how to use the QCborStreamReader class directly to
+    parse CBOR content.
+
+    \sa QCborStreamReader
+
+    \image cbordump.png
+
+    \section1 The Cbordumper Class
+
+    The Cbordumper class contains a QCborStreamReader object that is
+    initialized using the QFile object argument passed to the CborDumper
+    constructor. Based on the arguments the dump function calls either
+    dumpOne() or dumpOneDetailed() to dump the contents to stdout,
+
+    \snippet serialization/cbordump/main.cpp 0
+
+    \section2 The dumpOne() Function
+
+    The type() function of the QCborStreamReader is used in a switch statement
+    to print out for each type. If the type is an array or map, the content is
+    iterated upon, and for each entry the dumpOne() function is called
+    recursively with a higher indentation argument. If the type is a tag, it
+    is printed out and dumpOne() is called once without increasing the
+    indentation argument.
+
+    \section2 The dumpOneDetailed() Function
+
+    This function dumps out both the incoming bytes and the decoded contents
+    on the same line. It uses lambda functions to print out the bytes and
+    decoded content, but otherwise has a similar structure as dumpOne().
+
+    \section1 CborDescription
+
+    The tagDescriptions table, describing the CBOR-tags available, is
+    automatically generated from an XML-file available from the iana.org
+    website.
+
+    \sa {CBOR Support in Qt}
+    */
diff --git a/examples/corelib/serialization/cbordump/main.cpp b/examples/corelib/serialization/cbordump/main.cpp
index 126a5c5833..16ff27d701 100644
--- a/examples/corelib/serialization/cbordump/main.cpp
+++ b/examples/corelib/serialization/cbordump/main.cpp
@@ -87,6 +87,7 @@ enum {
     Value64Bit              = 27
 };
 
+//! [0]
 struct CborDumper
 {
     enum DumpOption {
@@ -113,6 +114,7 @@ private:
     qint64 offset = 0;
     DumpOptions opts;
 };
+//! [0]
 Q_DECLARE_OPERATORS_FOR_FLAGS(CborDumper::DumpOptions)
 
 static int cborNumberSize(quint64 value)
diff --git a/examples/corelib/serialization/convert/cborconverter.cpp b/examples/corelib/serialization/convert/cborconverter.cpp
index 0f49de2551..8c88d42af3 100644
--- a/examples/corelib/serialization/convert/cborconverter.cpp
+++ b/examples/corelib/serialization/convert/cborconverter.cpp
@@ -57,6 +57,7 @@ QT_END_NAMESPACE
 
 static QVariant convertCborValue(const QCborValue &value);
 
+//! [0]
 static QVariant convertCborMap(const QCborMap &map)
 {
     VariantOrderedMap result;
@@ -83,8 +84,9 @@ static QVariant convertCborValue(const QCborValue &value)
         return convertCborMap(value.toMap());
     return value.toVariant();
 }
-
+//! [0]
 enum TrimFloatingPoint { Double, Float, Float16 };
+//! [1]
 static QCborValue convertFromVariant(const QVariant &v, TrimFloatingPoint fpTrimming)
 {
     if (v.userType() == QMetaType::QVariantList) {
@@ -114,6 +116,7 @@ static QCborValue convertFromVariant(const QVariant &v, TrimFloatingPoint fpTrim
 
     return QCborValue::fromVariant(v);
 }
+//! [1]
 
 QString CborDiagnosticDumper::name()
 {
@@ -216,6 +219,7 @@ bool CborConverter::probeFile(QIODevice *f)
     return f->isReadable() && f->peek(3) == QByteArray("\xd9\xd9\xf7", 3);
 }
 
+//! [2]
 QVariant CborConverter::loadFile(QIODevice *f, Converter *&outputConverter)
 {
     const char *ptr = nullptr;
@@ -250,9 +254,11 @@ QVariant CborConverter::loadFile(QIODevice *f, Converter *&outputConverter)
         return contents.toVariant();
     return convertCborValue(contents);
 }
-
+//! [2]
+//! [3]
 void CborConverter::saveFile(QIODevice *f, const QVariant &contents, const QStringList &options)
 {
+    //! [3]
     bool useSignature = true;
     bool useIntegers = true;
     enum { Yes, No, Always } useFloat16 = Yes, useFloat = Yes;
@@ -311,7 +317,7 @@ void CborConverter::saveFile(QIODevice *f, const QVariant &contents, const QStri
                 qPrintable(s), optionHelp);
         exit(EXIT_FAILURE);
     }
-
+    //! [4]
     QCborValue v = convertFromVariant(contents,
                                       useFloat16 == Always ? Float16 : useFloat == Always ? Float : Double);
     QCborStreamWriter writer(f);
@@ -327,4 +333,4 @@ void CborConverter::saveFile(QIODevice *f, const QVariant &contents, const QStri
         opts |= QCborValue::UseFloat16;
     v.toCbor(writer, opts);
 }
-
+//! [4]
diff --git a/examples/corelib/serialization/convert/doc/images/convert.png b/examples/corelib/serialization/convert/doc/images/convert.png
new file mode 100644
index 0000000000..8d6816a626
--- /dev/null
+++ b/examples/corelib/serialization/convert/doc/images/convert.png
diff --git a/examples/corelib/serialization/convert/doc/src/convert.qdoc b/examples/corelib/serialization/convert/doc/src/convert.qdoc
new file mode 100644
index 0000000000..dc3264a469
--- /dev/null
+++ b/examples/corelib/serialization/convert/doc/src/convert.qdoc
@@ -0,0 +1,80 @@
+// Copyright (C) 2022 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+    \example serialization/convert
+    \title Convert Example
+
+    \brief The Convert example demonstrates how to convert between different
+    serialization formats.
+
+    The Convert example converts between the serialization formats JSON, CBOR,
+    XML, QDataStream and text. It can also auto detect the format being used.
+    Not all formats support both input and output, and they have different
+    sets of which types they support. QDataStream and XML are the richest,
+    followed by CBOR, then JSON, and then the plain text one.
+
+    \image convert.png
+
+    \section1 The Converter Class
+
+    The Converter class is the abstract superclass for all the converters to
+    and from all the formats. They all convert to and from the QVariant class,
+    which is used to represent all the datastructures internally.
+    The name() function returns the name of the converter. The directions()
+    function is used to determine if a converter can be used for input, output,
+    or both. The outputOptions() and optionsHelp() functions are used to get
+    and query which options are used by the different converters. The
+    probeFile() function is used to determine if a file has the same file
+    format as the converter. The loadFile() function deserializes the given
+    file, while the saveFile() serializes to the given file.
+
+    \section1 The CborConverter Class
+
+    The CborConverter class shows how to serialize to and from the CBOR-format.
+    There is also a CborDiagnosticDumper class to output in CBOR diagnostic
+    notation. That is similar to JSON, but not exactly, because it allows
+    displaying the contents of a CBOR stream losslessly, while a conversion
+    to JSON is lossy.
+
+    The convertCborValue() function is used to convert a QCborValue to a
+    QVariant. It uses the helper functions convertCborMap() and
+    convertCborArray().
+    \snippet serialization/convert/cborconverter.cpp 0
+
+    A CBOR-file is read using loadFile() function.
+    \snippet serialization/convert/cborconverter.cpp 2
+
+    The convertFromVariant() function is used to convert a QVariant to a
+    QCborValue.
+    \snippet serialization/convert/cborconverter.cpp 1
+
+    A CBOR-file is written using the saveFile() function.
+    \snippet serialization/convert/cborconverter.cpp 3
+    \snippet serialization/convert/cborconverter.cpp 4
+
+    \sa {CBOR Support in Qt}
+
+    \section1 The DataStreamConverter Class
+
+    The DataStreamConverter class is used to serialize to and from the
+    QDataStream format. There is also the DataStreamDumper class for outputting
+    the data lossless in a non-standardized human readable format.
+
+    \section1 The JsonConverter Class
+
+    The JsonConverter class is used to serialize to and from the JSON-format.
+    \sa {JSON Support in Qt}
+
+    \section1 The XmlConverter Class
+
+    The XmlConverter class is used to serialize to and from the XML-format.
+
+    \section1 The TextConverter Class
+
+    The TextConverter class is used to serialize to and from a text format.
+
+    \section1 The NullConverter Class
+
+    The NullConverter class is an output serializer that does nothing.
+*/
diff --git a/examples/corelib/serialization/savegame/doc/src/savegame.qdoc b/examples/corelib/serialization/savegame/doc/src/savegame.qdoc
index 0246ae48bb..233c81dd8b 100644
--- a/examples/corelib/serialization/savegame/doc/src/savegame.qdoc
+++ b/examples/corelib/serialization/savegame/doc/src/savegame.qdoc
@@ -158,5 +158,5 @@
     human-readable JSON files, but you also have the option to use a binary
     format if it's required, \e without rewriting any code.
 
-    \sa {JSON Support in Qt}, {Data Storage}
+    \sa {JSON Support in Qt}, {CBOR Support in Qt}, {Data Storage}
 */