doc: Fix warnings for BitsOfBinary* classes

8 files changed, 140 insertions, 50 deletions

diff --git a/src/base/QXmppBitsOfBinaryContentId.cpp b/src/base/QXmppBitsOfBinaryContentId.cpp
index 24722e62..928b1fae 100644
--- a/src/base/QXmppBitsOfBinaryContentId.cpp
+++ b/src/base/QXmppBitsOfBinaryContentId.cpp
@@ -63,14 +63,24 @@ QXmppBitsOfBinaryContentIdPrivate::QXmppBitsOfBinaryContentIdPrivate()
 {
 }
 
-/// Parses a \c QXmppBitsOfBinaryContentId from a \xep{0231}: Bits of Binary
+///
+/// \class QXmppBitsOfBinaryContentId
+///
+/// QXmppBitsOfBinaryContentId represents a link to or an identifier of
+/// \xep{0231, Bits of Binary} data.
+///
+/// \since QXmpp 1.2
+///
+
+///
+/// Parses a \c QXmppBitsOfBinaryContentId from a \xep{0231, Bits of Binary}
 /// \c cid: URL
 ///
 /// In case parsing failed, the returned \c QXmppBitsOfBinaryContentId is
 /// empty.
 ///
 /// \see QXmppBitsOfBinaryContentId::fromContentId
-
+///
 QXmppBitsOfBinaryContentId QXmppBitsOfBinaryContentId::fromCidUrl(const QString &input)
 {
     if (input.startsWith(CONTENTID_URL))
@@ -79,7 +89,8 @@ QXmppBitsOfBinaryContentId QXmppBitsOfBinaryContentId::fromCidUrl(const QString
     return {};
 }
 
-/// Parses a \c QXmppBitsOfBinaryContentId from a \xep{0231}: Bits of Binary
+///
+/// Parses a \c QXmppBitsOfBinaryContentId from a \xep{0231, Bits of Binary}
 /// content id
 ///
 /// In case parsing failed, the returned \c QXmppBitsOfBinaryContentId is
@@ -89,7 +100,7 @@ QXmppBitsOfBinaryContentId QXmppBitsOfBinaryContentId::fromCidUrl(const QString
 /// \c QXmppBitsOfBinaryContentId::fromCidUrl for that purpose.
 ///
 /// \see QXmppBitsOfBinaryContentId::fromCidUrl
-
+///
 QXmppBitsOfBinaryContentId QXmppBitsOfBinaryContentId::fromContentId(const QString &input)
 {
     if (input.startsWith(CONTENTID_URL) || !input.endsWith(CONTENTID_POSTFIX))
@@ -113,28 +124,34 @@ QXmppBitsOfBinaryContentId QXmppBitsOfBinaryContentId::fromContentId(const QStri
     return cid;
 }
 
+///
 /// Default contructor
-
+///
 QXmppBitsOfBinaryContentId::QXmppBitsOfBinaryContentId()
     : d(new QXmppBitsOfBinaryContentIdPrivate)
 {
 }
 
+///
 /// Returns true, if two \c QXmppBitsOfBinaryContentId equal
-
+///
 bool QXmppBitsOfBinaryContentId::operator==(const QXmppBitsOfBinaryContentId &other) const
 {
     return d->algorithm == other.algorithm() && d->hash == other.hash();
 }
 
+/// Default destructor
 QXmppBitsOfBinaryContentId::~QXmppBitsOfBinaryContentId() = default;
 
+/// Default copy-constructor
 QXmppBitsOfBinaryContentId::QXmppBitsOfBinaryContentId(const QXmppBitsOfBinaryContentId &cid) = default;
 
+/// Default assignment operator
 QXmppBitsOfBinaryContentId &QXmppBitsOfBinaryContentId::operator=(const QXmppBitsOfBinaryContentId &other) = default;
 
-/// Returns a \xep{0231}: Bits of Binary content id
-
+///
+/// Returns a \xep{0231, Bits of Binary} content id
+///
 QString QXmppBitsOfBinaryContentId::toContentId() const
 {
     if (!isValid())
@@ -146,8 +163,9 @@ QString QXmppBitsOfBinaryContentId::toContentId() const
         CONTENTID_POSTFIX;
 }
 
-/// Returns a \xep{0231}: Bits of Binary \c cid: URL
-
+///
+/// Returns a \xep{0231, Bits of Binary} \c cid: URL
+///
 QString QXmppBitsOfBinaryContentId::toCidUrl() const
 {
     if (!isValid())
@@ -156,32 +174,36 @@ QString QXmppBitsOfBinaryContentId::toCidUrl() const
     return toContentId().prepend(CONTENTID_URL);
 }
 
+///
 /// Returns the hash value in binary form
-
+///
 QByteArray QXmppBitsOfBinaryContentId::hash() const
 {
     return d->hash;
 }
 
+///
 /// Sets the hash value in binary form
-
+///
 void QXmppBitsOfBinaryContentId::setHash(const QByteArray &hash)
 {
     d->hash = hash;
 }
 
+///
 /// Returns the hash algorithm used to calculate the \c hash value
 ///
 /// The default value is \c QCryptographicHash::Sha1.
 ///
 /// This currently supports MD4, MD5, SHA-1, SHA-2 (SHA224 - SHA512) and SHA-3
 /// (SHA3-224 - SHA3-512).
-
+///
 QCryptographicHash::Algorithm QXmppBitsOfBinaryContentId::algorithm() const
 {
     return d->algorithm;
 }
 
+///
 /// Sets the hash algorithm used to calculate the \c hash value
 ///
 /// The default value is \c QCryptographicHash::Sha1.
@@ -193,12 +215,13 @@ QCryptographicHash::Algorithm QXmppBitsOfBinaryContentId::algorithm() const
 /// hashing algorithms than SHA-1 to be used, but not all clients support this.
 /// Since in most cases the content id is not security relevant it is not a
 /// problem to continue using SHA-1.
-
+///
 void QXmppBitsOfBinaryContentId::setAlgorithm(QCryptographicHash::Algorithm algo)
 {
     d->algorithm = algo;
 }
 
+///
 /// Checks whether the content id is valid and can be serialized into a string.
 ///
 /// \note Checking the hash length requires QXmpp to be built with Qt 5.12.0 or
@@ -206,7 +229,7 @@ void QXmppBitsOfBinaryContentId::setAlgorithm(QCryptographicHash::Algorithm algo
 ///
 /// \returns True, if the set hashing algorithm is supported, a hash value is
 /// set and its length is correct, false otherwise.
-
+///
 bool QXmppBitsOfBinaryContentId::isValid() const
 {
 #if QT_VERSION >= QT_VERSION_CHECK(5, 12, 0)
@@ -218,12 +241,14 @@ bool QXmppBitsOfBinaryContentId::isValid() const
 #endif
 }
 
+///
 /// Checks whether \c input is a Bits of Binary content id or \c cid: URL
 ///
+/// \param input The string to be checked.
 /// \param checkIsCidUrl If true, it only accepts \c cid: URLs.
 ///
 /// \returns True, if \c input is valid.
-
+///
 bool QXmppBitsOfBinaryContentId::isBitsOfBinaryContentId(const QString &input, bool checkIsCidUrl)
 {
     return input.endsWith(CONTENTID_POSTFIX) &&
diff --git a/src/base/QXmppBitsOfBinaryContentId.h b/src/base/QXmppBitsOfBinaryContentId.h
index 3ca9b427..720b60d6 100644
--- a/src/base/QXmppBitsOfBinaryContentId.h
+++ b/src/base/QXmppBitsOfBinaryContentId.h
@@ -31,11 +31,6 @@
 
 class QXmppBitsOfBinaryContentIdPrivate;
 
-/// \class QXmppBitsOfBinaryContentId represents a link to or an identifier of
-/// \xep{0231}: Bits of Binary data.
-///
-/// \since QXmpp 1.2
-
 class QXMPP_EXPORT QXmppBitsOfBinaryContentId
 {
 public:
diff --git a/src/base/QXmppBitsOfBinaryData.cpp b/src/base/QXmppBitsOfBinaryData.cpp
index 77dc9131..14797fb3 100644
--- a/src/base/QXmppBitsOfBinaryData.cpp
+++ b/src/base/QXmppBitsOfBinaryData.cpp
@@ -49,88 +49,114 @@ QXmppBitsOfBinaryDataPrivate::QXmppBitsOfBinaryDataPrivate()
 {
 }
 
+///
+/// \class QXmppBitsOfBinaryData
+///
+/// QXmppBitsOfBinaryData represents a data element for \xep{0231, Bits of
+/// Binary}. It can be used as an extension in other stanzas.
+///
+/// \see QXmppBitsOfBinaryIq, QXmppBitsOfBinaryDataList
+///
+/// \since QXmpp 1.2
+///
+
+///
+/// Default constructor
+///
 QXmppBitsOfBinaryData::QXmppBitsOfBinaryData()
     : d(new QXmppBitsOfBinaryDataPrivate)
 {
 }
 
+/// Default copy-constructor
 QXmppBitsOfBinaryData::QXmppBitsOfBinaryData(const QXmppBitsOfBinaryData &) = default;
 
+/// Default destructor
 QXmppBitsOfBinaryData::~QXmppBitsOfBinaryData() = default;
 
+/// Default assignment operator
 QXmppBitsOfBinaryData &QXmppBitsOfBinaryData::operator=(const QXmppBitsOfBinaryData &) = default;
 
+///
 /// Returns the content id of the data
-
+///
 QXmppBitsOfBinaryContentId QXmppBitsOfBinaryData::cid() const
 {
     return d->cid;
 }
 
+///
 /// Sets the content id of the data
-
+///
 void QXmppBitsOfBinaryData::setCid(const QXmppBitsOfBinaryContentId &cid)
 {
     d->cid = cid;
 }
 
+///
 /// Returns the time in seconds the data should be cached
 ///
 /// A value of 0 means that the data should not be cached, while a value of -1
 /// means that nothing was set.
 ///
 /// The default value is -1.
-
+///
 int QXmppBitsOfBinaryData::maxAge() const
 {
     return d->maxAge;
 }
 
+///
 /// Sets the time in seconds the data should be cached
 ///
 /// A value of 0 means that the data should not be cached, while a value of -1
 /// means that nothing was set.
 ///
 /// The default value is -1.
-
+///
 void QXmppBitsOfBinaryData::setMaxAge(int maxAge)
 {
     d->maxAge = maxAge;
 }
 
+///
 /// Returns the content type of the data
 ///
 /// \note This is the advertised content type and may differ from the actual
 /// content type of the data.
-
+///
 QMimeType QXmppBitsOfBinaryData::contentType() const
 {
     return d->contentType;
 }
 
+///
 /// Sets the content type of the data
-
+///
 void QXmppBitsOfBinaryData::setContentType(const QMimeType &contentType)
 {
     d->contentType = contentType;
 }
 
+///
 /// Returns the included data in binary form
-
+///
 QByteArray QXmppBitsOfBinaryData::data() const
 {
     return d->data;
 }
 
+///
 /// Sets the data in binary form
-
+///
 void QXmppBitsOfBinaryData::setData(const QByteArray &data)
 {
     d->data = data;
 }
 
-/// Returns true, if \c element is a \xep{0231}: Bits of Binary data element
-
+///
+/// Returns true, if \c element is a \xep{0231, Bits of Binary} data element
+///
 bool QXmppBitsOfBinaryData::isBitsOfBinaryData(const QDomElement &element)
 {
     return element.tagName() == QStringLiteral("data") && element.namespaceURI() == ns_bob;
@@ -158,6 +184,9 @@ void QXmppBitsOfBinaryData::toXmlElementFromChild(QXmlStreamWriter *writer) cons
 }
 /// \endcond
 
+///
+/// Returns true, if cid, maxAge, contentType and data equal.
+///
 bool QXmppBitsOfBinaryData::operator==(const QXmppBitsOfBinaryData &other) const
 {
     return d->cid == other.cid() &&
@@ -165,3 +194,42 @@ bool QXmppBitsOfBinaryData::operator==(const QXmppBitsOfBinaryData &other) const
         d->contentType == other.contentType() &&
         d->data == other.data();
 }
+
+///
+/// \class QXmppBitsOfBinaryDataList
+///
+/// QXmppBitsOfBinaryDataList represents a list of data elements from
+/// \xep{0231, Bits of Binary}.
+///
+/// \since QXmpp 1.2
+///
+
+QXmppBitsOfBinaryDataList::QXmppBitsOfBinaryDataList() = default;
+
+QXmppBitsOfBinaryDataList::~QXmppBitsOfBinaryDataList() = default;
+
+/// \cond
+void QXmppBitsOfBinaryDataList::parse(const QDomElement &element)
+{
+    // clear previous data elements
+    clear();
+
+    // parse all <data/> elements
+    QDomElement child = element.firstChildElement();
+    while (!child.isNull()) {
+        if (QXmppBitsOfBinaryData::isBitsOfBinaryData(child)) {
+            QXmppBitsOfBinaryData data;
+            data.parseElementFromChild(child);
+            append(data);
+        }
+        child = child.nextSiblingElement();
+    }
+}
+
+void QXmppBitsOfBinaryDataList::toXml(QXmlStreamWriter *writer) const
+{
+    for (const auto &bitsOfBinaryData : *this) {
+        bitsOfBinaryData.toXmlElementFromChild(writer);
+    }
+}
+/// \endcond
diff --git a/src/base/QXmppBitsOfBinaryData.h b/src/base/QXmppBitsOfBinaryData.h
index fa75bdf1..4a8646ac 100644
--- a/src/base/QXmppBitsOfBinaryData.h
+++ b/src/base/QXmppBitsOfBinaryData.h
@@ -34,13 +34,6 @@ class QXmlStreamWriter;
 class QXmppBitsOfBinaryDataPrivate;
 class QXmppBitsOfBinaryContentId;
 
-/// \class QXmppBitsOfBinaryData represents a data element for \xep{0231}: Bits
-/// of Binary. It can be used as an extension in other stanzas.
-///
-/// \see QXmppBitsOfBinaryIq, QXmppBitsOfBinaryDataList
-///
-/// \since QXmpp 1.2
-
 class QXMPP_EXPORT QXmppBitsOfBinaryData
 {
 public:
diff --git a/src/base/QXmppBitsOfBinaryDataList.cpp b/src/base/QXmppBitsOfBinaryDataList.cpp
index f4239979..fda17ff7 100644
--- a/src/base/QXmppBitsOfBinaryDataList.cpp
+++ b/src/base/QXmppBitsOfBinaryDataList.cpp
@@ -28,6 +28,15 @@
 
 #include <QDomElement>
 
+///
+/// \class QXmppBitsOfBinaryDataList
+///
+/// QXmppBitsOfBinaryDataList represents a list of data elements from
+/// \xep{0231, Bits of Binary}.
+///
+/// \since QXmpp 1.2
+///
+
 QXmppBitsOfBinaryDataList::QXmppBitsOfBinaryDataList() = default;
 
 QXmppBitsOfBinaryDataList::~QXmppBitsOfBinaryDataList() = default;
diff --git a/src/base/QXmppBitsOfBinaryDataList.h b/src/base/QXmppBitsOfBinaryDataList.h
index 6510f3a7..d6cf87e3 100644
--- a/src/base/QXmppBitsOfBinaryDataList.h
+++ b/src/base/QXmppBitsOfBinaryDataList.h
@@ -31,11 +31,6 @@
 class QDomElement;
 class QXmlStreamWriter;
 
-/// \class QXmppBitsOfBinaryDataList represents a list of data elements from
-/// \xep{0231}: Bits of Binary.
-///
-/// \since QXmpp 1.2
-
 class QXMPP_EXPORT QXmppBitsOfBinaryDataList : public QVector<QXmppBitsOfBinaryData>
 {
 public:
diff --git a/src/base/QXmppBitsOfBinaryIq.cpp b/src/base/QXmppBitsOfBinaryIq.cpp
index 65cbd754..44dc0dc3 100644
--- a/src/base/QXmppBitsOfBinaryIq.cpp
+++ b/src/base/QXmppBitsOfBinaryIq.cpp
@@ -28,15 +28,25 @@
 #include <QDomElement>
 #include <QSharedData>
 
+///
+/// \class QXmppBitsOfBinaryIq
+///
+/// QXmppBitsOfBinaryIq represents a \xep{0231, Bits of Binary} IQ to request
+/// and transmit Bits of Binary data elements.
+///
+/// \since QXmpp 1.2
+///
+
 QXmppBitsOfBinaryIq::QXmppBitsOfBinaryIq() = default;
 
 QXmppBitsOfBinaryIq::~QXmppBitsOfBinaryIq() = default;
 
-/// Returns true, if \c element is a \xep{0231}: Bits of Binary IQ
+///
+/// Returns true, if \c element is a \xep{0231, Bits of Binary} IQ
 ///
 /// \note This may also return true, if the IQ is not a Bits of Binary IQ in
 /// first place, but only contains a Bits of Binary data element.
-
+///
 bool QXmppBitsOfBinaryIq::isBitsOfBinaryIq(const QDomElement &element)
 {
     QDomElement child = element.firstChildElement();
diff --git a/src/base/QXmppBitsOfBinaryIq.h b/src/base/QXmppBitsOfBinaryIq.h
index 902e04c0..c8e9c19e 100644
--- a/src/base/QXmppBitsOfBinaryIq.h
+++ b/src/base/QXmppBitsOfBinaryIq.h
@@ -27,11 +27,6 @@
 #include "QXmppBitsOfBinaryData.h"
 #include "QXmppIq.h"
 
-/// \class QXmppBitsOfBinaryIq represents a \xep{0231}: Bits of Binary IQ to
-/// request and transmit Bits of Binary data elements.
-///
-/// \since QXmpp 1.2
-
 class QXMPP_EXPORT QXmppBitsOfBinaryIq : public QXmppIq, public QXmppBitsOfBinaryData
 {
 public: