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>

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}
+    */

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)

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]

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.
+*/

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}
 */

src/corelib/doc/src/cbor.qdoc

@@ -0,0 +1,78 @@
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+    \group cbor
+    \title CBOR Support in Qt
+    \ingroup qt-basic-concepts
+    \brief An overview of CBOR support in Qt.
+
+    \ingroup frameworks-technologies
+
+    \keyword CBOR
+
+    Qt provides support for dealing with CBOR data. CBOR is a binary format to
+    store data that has a superset of the types available in JSON, but is more
+    compact.
+
+    The CBOR support in Qt provides an easy to use C++ API to parse,
+    modify and save CBOR data.
+
+    More details about the CBOR data format can be found in \l {RFC 7049}.
+
+    \tableofcontents
+
+    \section1 Overview
+
+    CBOR is a format to store structured data. It has three groups of built-in types:
+
+    \list
+    \li Basic types: integers, floating point, boolean, null, etc.
+    \li String-like types: strings and byte arrays
+    \li Containers: arrays and maps
+    \endlist
+
+    In addition, CBOR can add a "tag" to extend the meaning of the type. The
+    container types can contain basic types, string-like types and containers.
+
+    \sa {Cbordump Example}, {Convert Example}, {JSON Save Game Example}
+
+    \section1 The CBOR Classes
+
+    \section2 The QCborValue Class
+
+    The QCborValue class represents any CBOR type. It also has a simple API for
+    reading and writing to QCborStreamReader and QCborStreamWriter objects, as
+    well as manipulating such objects in memory, with the help of QCborArray
+    and QCborMap. The CborValue API is simplified from the full CBOR data type
+    and always represents all integers as \l qint64 and all floating-point as
+    \c double. This means QCborValue is unable to represent CBOR integer values
+    outside of the range of \l qint64 (-2^63 to 2^63-1). When creating a CBOR
+    stream, QCborValue::toCbor() can be configured to attempt to write the
+    shorter single- and half-precision floating-point representations.
+
+    \section2 The QCborArray Class
+
+    The QCborArray class is used to hold an array of QCborValue objects. A
+    QCborValue object can contain a QCborArray object. It has functions for
+    converting to and from QVariantList, QStringList, QJsonArray.
+
+    \section2 The QCborMap Class
+
+    The QCborMap class is used to hold an map of QCborValue objects. A
+    QCborValue object can contain a QCborMap object. It has functions for
+    converting to and from QVariantMap, QVariantMap, and QJsonObject, but it
+    can have keys of any type, not just QString.
+
+    \section2 The QCborStreamReader Class
+
+    The QCborStreamReader class is a low level API for reading CBOR data from a
+    QIODevice, a QByteArray, or a pointer to memory. It has an API similar to
+    the QXmlStreamReader class.
+
+    \section2 The QCborStreamWriter Class
+
+    The QCborStreamWriter class is a low level API for writing CBOR data to a
+    QIODevice or a QByteArray. It has an API similar to the QXmlStreamWriter
+    class.
+*/

src/corelib/doc/src/datastreamformat.qdoc

@@ -67,5 +67,6 @@
     \li QVector4D
     \endlist
 
-    \sa {JSON Support in Qt}
+    \sa {JSON Support in Qt}, {CBOR Support in Qt}
+
 */

src/corelib/doc/src/qtcore-index.qdoc

@@ -75,6 +75,7 @@
     \list
     \li \l{The Animation Framework}
     \li \l{JSON Support in Qt}
+    \li \l{CBOR Support in Qt}
     \li \l{How to Create Qt Plugins}
     \li \l{The Event System}
     \endlist

src/corelib/serialization/qcborarray.cpp

@@ -30,7 +30,8 @@ using namespace QtCbor;
     from those two, though there may be loss of information in some
     conversions.
 
-    \sa QCborValue, QCborMap, QJsonArray, QList
+    \sa QCborValue, QCborMap, QJsonArray, QList, {Cbordump Example},
+        {Convert Example}, {JSON Save Game Example}
  */
 
 /*!

src/corelib/serialization/qcborcommon.cpp

@@ -179,6 +179,7 @@ QDataStream &operator>>(QDataStream &ds, QCborSimpleType &st)
    validating a CBOR stream.
 
    \sa QCborStreamReader, QCborValue, QCborParserError
+   \sa {Cbordump Example}, {Convert Example}, {JSON Save Game Example}
  */
 
 /*!

src/corelib/serialization/qcbormap.cpp

@@ -46,7 +46,8 @@ using namespace QtCbor;
     stringified using a one-way method that the conversion back to QCborMap
     will not undo.
 
-    \sa QCborArray, QCborValue, QJsonDocument, QVariantMap
+    \sa QCborArray, QCborValue, QJsonDocument, QVariantMap, {Cbordump Example}
+    \sa {Convert Example}, {JSON Save Game Example}
  */
 
 /*!

src/corelib/serialization/qcborstreamreader.cpp

@@ -151,7 +151,8 @@ static_assert(int(QCborStreamReader::Invalid) == CborInvalidType);
    parsing from a QByteArray, or reparse(), if it is instead reading directly
    a the QIDOevice that now has more data available (see setDevice()).
 
-   \sa QCborStreamWriter, QCborValue, QXmlStreamReader
+   \sa QCborStreamWriter, QCborValue, QXmlStreamReader, {Cbordump Example}
+   \sa {Convert Example}, {JSON Save Game Example}
  */
 
 /*!

src/corelib/serialization/qcborstreamwriter.cpp

@@ -175,6 +175,7 @@ Q_DECLARE_TYPEINFO(CborEncoder, Q_PRIMITIVE_TYPE);
    \endlist
 
    \sa QCborStreamReader, QCborValue, QXmlStreamWriter
+   \sa {Cbordump Example}, {Convert Example}, {JSON Save Game Example}
  */
 
 class QCborStreamWriterPrivate

src/corelib/serialization/qcborvalue.cpp

@@ -189,7 +189,8 @@ Q_DECL_UNUSED static constexpr quint64 MaximumPreallocatedElementCount =
     aspects, its API is identical to QCborValue.
 
     \sa QCborArray, QCborMap, QCborStreamReader, QCborStreamWriter
-        QJsonValue, QJsonDocument
+    \sa QJsonValue, QJsonDocument, {Cbordump Example}, {Convert Example}
+    \sa {JSON Save Game Example}
  */
 
 /*!