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>

9 files changed, 91 insertions, 5 deletions

diff --git a/src/corelib/doc/src/cbor.qdoc b/src/corelib/doc/src/cbor.qdoc
new file mode 100644
index 0000000000..22252bbd88
--- /dev/null
+++ b/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.
+*/
diff --git a/src/corelib/doc/src/datastreamformat.qdoc b/src/corelib/doc/src/datastreamformat.qdoc
index ae8e155bea..b1b2e6ba34 100644
--- a/src/corelib/doc/src/datastreamformat.qdoc
+++ b/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}
+
 */
diff --git a/src/corelib/doc/src/qtcore-index.qdoc b/src/corelib/doc/src/qtcore-index.qdoc
index 377e199784..99cc114d64 100644
--- a/src/corelib/doc/src/qtcore-index.qdoc
+++ b/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
diff --git a/src/corelib/serialization/qcborarray.cpp b/src/corelib/serialization/qcborarray.cpp
index 1c8d21af47..95fd47b767 100644
--- a/src/corelib/serialization/qcborarray.cpp
+++ b/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}
  */
 
 /*!
diff --git a/src/corelib/serialization/qcborcommon.cpp b/src/corelib/serialization/qcborcommon.cpp
index 648ca59d8b..9168b8c520 100644
--- a/src/corelib/serialization/qcborcommon.cpp
+++ b/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}
  */
 
 /*!
diff --git a/src/corelib/serialization/qcbormap.cpp b/src/corelib/serialization/qcbormap.cpp
index b3b9ea2691..c8895cb42a 100644
--- a/src/corelib/serialization/qcbormap.cpp
+++ b/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}
  */
 
 /*!
diff --git a/src/corelib/serialization/qcborstreamreader.cpp b/src/corelib/serialization/qcborstreamreader.cpp
index 10b3eb2d45..65edd3a941 100644
--- a/src/corelib/serialization/qcborstreamreader.cpp
+++ b/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}
  */
 
 /*!
diff --git a/src/corelib/serialization/qcborstreamwriter.cpp b/src/corelib/serialization/qcborstreamwriter.cpp
index 9f7e30e8cb..0e445451bc 100644
--- a/src/corelib/serialization/qcborstreamwriter.cpp
+++ b/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
diff --git a/src/corelib/serialization/qcborvalue.cpp b/src/corelib/serialization/qcborvalue.cpp
index c136e80755..1df4a16e97 100644
--- a/src/corelib/serialization/qcborvalue.cpp
+++ b/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}
  */
 
 /*!