fix some documentation warnings

5 files changed, 46 insertions, 13 deletions

diff --git a/src/base/QXmppJingleIq.h b/src/base/QXmppJingleIq.h
index c735d051..87bf63f6 100644
--- a/src/base/QXmppJingleIq.h
+++ b/src/base/QXmppJingleIq.h
@@ -125,12 +125,12 @@ public:
 
     bool isNull() const;
 
-    static QXmppJingleCandidate::Type typeFromString(const QString &typeStr, bool *ok = 0);
-    static QString typeToString(QXmppJingleCandidate::Type type);
-
     /// \cond
     void parse(const QDomElement &element);
     void toXml(QXmlStreamWriter *writer) const;
+
+    static QXmppJingleCandidate::Type typeFromString(const QString &typeStr, bool *ok = 0);
+    static QString typeToString(QXmppJingleCandidate::Type type);
     /// \endcond
 
 private:
diff --git a/src/base/QXmppMucIq.cpp b/src/base/QXmppMucIq.cpp
index 97328a2f..30dc9697 100644
--- a/src/base/QXmppMucIq.cpp
+++ b/src/base/QXmppMucIq.cpp
@@ -33,6 +33,8 @@ QXmppMucItem::QXmppMucItem()
 {
 }
 
+/// Returns true if the current item is null.
+
 bool QXmppMucItem::isNull() const
 {
     return m_actor.isEmpty() &&
@@ -43,11 +45,17 @@ bool QXmppMucItem::isNull() const
            m_role == UnspecifiedRole;
 }
 
+/// Returns the actor for this item, for instance the admin who kicked
+/// a user out of a room.
+
 QString QXmppMucItem::actor() const
 {
     return m_actor;
 }
 
+/// Sets the \a actor for this item, for instance the admin who kicked
+/// a user out of a room.
+
 void QXmppMucItem::setActor(const QString &actor)
 {
     m_actor = actor;
@@ -135,11 +143,17 @@ void QXmppMucItem::setNick(const QString &nick)
     m_nick = nick;
 }
 
+/// Returns the reason for this item, for example the reason for kicking
+/// a user out of a room.
+
 QString QXmppMucItem::reason() const
 {
     return m_reason;
 }
 
+/// Sets the \a reason for this item, for example the reason for kicking
+/// a user out of a room.
+
 void QXmppMucItem::setReason(const QString &reason)
 {
     m_reason = reason;
diff --git a/src/base/QXmppMucIq.h b/src/base/QXmppMucIq.h
index 173588a7..156f7192 100644
--- a/src/base/QXmppMucIq.h
+++ b/src/base/QXmppMucIq.h
@@ -76,10 +76,10 @@ public:
     Role role() const;
     void setRole(Role role);
 
+    /// \cond
     void parse(const QDomElement &element);
     void toXml(QXmlStreamWriter *writer) const;
 
-    /// \cond
     static Affiliation affiliationFromString(const QString &affiliationStr);
     static QString affiliationToString(Affiliation affiliation);
     static Role roleFromString(const QString &roleStr);
diff --git a/src/base/QXmppStun.cpp b/src/base/QXmppStun.cpp
index ab596886..be8721e0 100644
--- a/src/base/QXmppStun.cpp
+++ b/src/base/QXmppStun.cpp
@@ -1565,7 +1565,6 @@ QString QXmppIceComponent::Pair::toString() const
 
 /// Constructs a new QXmppIceComponent.
 ///
-/// \param controlling
 /// \param parent
 
 QXmppIceComponent::QXmppIceComponent(QObject *parent)
@@ -1719,6 +1718,8 @@ bool QXmppIceComponent::isConnected() const
     return m_activePair != 0;
 }
 
+/// Sets whether the local party has the ICE controlling role.
+
 void QXmppIceComponent::setIceControlling(bool controlling)
 {
     m_iceControlling = controlling;
@@ -2294,7 +2295,6 @@ qint64 QXmppIceComponent::writeStun(const QXmppStunMessage &message, QXmppIceCom
 
 /// Constructs a new ICE connection.
 ///
-/// \param controlling
 /// \param parent
 
 QXmppIceConnection::QXmppIceConnection(QObject *parent)
@@ -2434,6 +2434,8 @@ bool QXmppIceConnection::isConnected() const
     return true;
 }
 
+/// Sets whether the local party has the ICE controlling role.
+
 void QXmppIceConnection::setIceControlling(bool controlling)
 {
     m_iceControlling = controlling;
diff --git a/src/base/QXmppUtils.cpp b/src/base/QXmppUtils.cpp
index f308710c..97ce8e1e 100644
--- a/src/base/QXmppUtils.cpp
+++ b/src/base/QXmppUtils.cpp
@@ -107,6 +107,9 @@ static quint32 crctable[256] =
     0xB40BBE37L, 0xC30C8EA1L, 0x5A05DF1BL, 0x2D02EF8DL
 };
 
+/// Parses a date-time from a string according to
+/// XEP-0082: XMPP Date and Time Profiles.
+
 QDateTime QXmppUtils::datetimeFromString(const QString &str)
 {
     QRegExp tzRe("(Z|([+-])([0-9]{2}):([0-9]{2}))");
@@ -137,6 +140,9 @@ QDateTime QXmppUtils::datetimeFromString(const QString &str)
     return dt;
 }
 
+/// Serializes a date-time to a string according to
+/// XEP-0082: XMPP Date and Time Profiles.
+
 QString QXmppUtils::datetimeToString(const QDateTime &dt)
 {
     QDateTime utc = dt.toUTC();
@@ -146,10 +152,8 @@ QString QXmppUtils::datetimeToString(const QDateTime &dt)
         return utc.toString("yyyy-MM-ddThh:mm:ssZ");
 }
 
-/// Parses a timezone offset (in seconds) from a string.
-///
-/// \param str
-///
+/// Parses a timezone offset (in seconds) from a string according to
+/// XEP-0082: XMPP Date and Time Profiles.
 
 int QXmppUtils::timezoneOffsetFromString(const QString &str)
 {
@@ -170,9 +174,8 @@ int QXmppUtils::timezoneOffsetFromString(const QString &str)
         return offset;
 }
 
-/// Serializes a timezone offset (in seconds) to a string.
-///
-/// \param secs
+/// Serializes a timezone offset (in seconds) to a string according to
+/// XEP-0082: XMPP Date and Time Profiles.
 
 QString QXmppUtils::timezoneOffsetToString(int secs)
 {
@@ -183,11 +186,15 @@ QString QXmppUtils::timezoneOffsetToString(int secs)
     return (secs < 0 ? "-" : "+") + tzoTime.toString("hh:mm");
 }
 
+/// Returns the domain for the given \a jid.
+
 QString QXmppUtils::jidToDomain(const QString &jid)
 {
     return jidToBareJid(jid).split("@").last();
 }
 
+/// Returns the resource for the given \a jid.
+
 QString QXmppUtils::jidToResource(const QString& jid)
 {
     const int pos = jid.indexOf(QChar('/'));
@@ -196,6 +203,8 @@ QString QXmppUtils::jidToResource(const QString& jid)
     return jid.mid(pos+1);
 }
 
+/// Returns the user for the given \a jid.
+
 QString QXmppUtils::jidToUser(const QString &jid)
 {
     const int pos = jid.indexOf(QChar('@'));
@@ -204,6 +213,8 @@ QString QXmppUtils::jidToUser(const QString &jid)
     return jid.left(pos);
 }
 
+/// Returns the bare jid (i.e. without resource) for the given \a jid.
+
 QString QXmppUtils::jidToBareJid(const QString& jid)
 {
     const int pos = jid.indexOf(QChar('/'));
@@ -212,6 +223,8 @@ QString QXmppUtils::jidToBareJid(const QString& jid)
     return jid.left(pos);
 }
 
+/// Calculates the CRC32 checksum for the given input.
+
 quint32 QXmppUtils::generateCrc32(const QByteArray &in)
 {
     quint32 result = 0xffffffff;
@@ -243,11 +256,15 @@ static QByteArray generateHmac(QCryptographicHash::Algorithm algorithm, const QB
     return hasher.result();
 }
 
+/// Generates the MD5 HMAC for the given \a key and \a text.
+
 QByteArray QXmppUtils::generateHmacMd5(const QByteArray &key, const QByteArray &text)
 {
     return generateHmac(QCryptographicHash::Md5, key, text);
 }
 
+/// Generates the SHA1 HMAC for the given \a key and \a text.
+
 QByteArray QXmppUtils::generateHmacSha1(const QByteArray &key, const QByteArray &text)
 {
     return generateHmac(QCryptographicHash::Sha1, key, text);