improve code documentation

19 files changed, 127 insertions, 48 deletions

diff --git a/source/QXmppBind.h b/source/QXmppBind.h
index 30f2fdb3..04a5d858 100644
--- a/source/QXmppBind.h
+++ b/source/QXmppBind.h
@@ -36,16 +36,17 @@ public:
     
     QString jid() const;
     QString resource() const;
+
     void setJid(const QString&);
     void setResource(const QString&);
 
     static bool isBind(const QDomElement &element);
 
-// deprecated accessors, use the form without "get" instead
-// obsolete start
+    // deprecated accessors, use the form without "get" instead
+    /// \cond
     QString Q_DECL_DEPRECATED getJid() const;
     QString Q_DECL_DEPRECATED getResource() const;
-// obsolete end
+    /// \endcond
 
 protected:
     void parseElementFromChild(const QDomElement &element);
diff --git a/source/QXmppCallManager.cpp b/source/QXmppCallManager.cpp
index 09c49d43..3dbd56c3 100644
--- a/source/QXmppCallManager.cpp
+++ b/source/QXmppCallManager.cpp
@@ -102,6 +102,9 @@ void QXmppCall::accept()
         setState(QXmppCall::ConnectingState);
 }
 
+/// Returns the number of bytes that are available for reading.
+///
+
 qint64 QXmppCall::bytesAvailable() const
 {
     return m_incomingBuffer.size();
@@ -149,6 +152,9 @@ void QXmppCall::emitSignals()
     m_signalsEmitted = false;
 }
 
+/// Hangs up the call.
+///
+
 void QXmppCall::hangup()
 {
     if (m_state != QXmppCall::FinishedState)
@@ -160,6 +166,9 @@ bool QXmppCall::isSequential() const
     return true;
 }
 
+/// Returns the remote party's JID.
+///
+
 QString QXmppCall::jid() const
 {
     return m_jid;
@@ -330,13 +339,18 @@ void QXmppCall::datagramReceived(const QByteArray &buffer)
     emit readyRead();
 }
 
-/// Returns the session identifier for this call.
+/// Returns the call's session identifier.
+///
 
 QString QXmppCall::sid() const
 {
     return m_sid;
 }
 
+/// Returns the call's state.
+///
+/// \sa stateChanged()
+
 QXmppCall::State QXmppCall::state() const
 {
     return m_state;
diff --git a/source/QXmppCallManager.h b/source/QXmppCallManager.h
index a16e3717..ea397ab5 100644
--- a/source/QXmppCallManager.h
+++ b/source/QXmppCallManager.h
@@ -49,19 +49,21 @@ class QXmppCall : public QIODevice
     Q_OBJECT
 
 public:
+    /// This enum is used to describe the direction of a call.
     enum Direction
     {
         IncomingDirection, ///< The call is incoming.
         OutgoingDirection, ///< The call is outgoing.
     };
 
+    /// This enum is used to describe the state of a call.
     enum State
     {
-        OfferState = 0,
-        ConnectingState = 1,
-        ActiveState = 2,
-        DisconnectingState = 3,
-        FinishedState = 4,
+        OfferState = 0,         ///< The remote part is being called.
+        ConnectingState = 1,    ///< The call is being connected.
+        ActiveState = 2,        ///< The call is active.
+        DisconnectingState = 3, ///< The call is being disconnected.
+        FinishedState = 4,      ///< The call is finished.
     };
 
     QXmppCall::Direction direction() const;
diff --git a/source/QXmppConfiguration.h b/source/QXmppConfiguration.h
index c0a070ed..8300da82 100644
--- a/source/QXmppConfiguration.h
+++ b/source/QXmppConfiguration.h
@@ -116,8 +116,8 @@ public:
 
     void setNetworkProxy(const QNetworkProxy& proxy);
 
-// deprecated accessors, use the form without "get" instead
-// obsolete start
+    // deprecated accessors, use the form without "get" instead
+    /// \cond
     QString Q_DECL_DEPRECATED getHost() const;
     QString Q_DECL_DEPRECATED getDomain() const;
     int Q_DECL_DEPRECATED getPort() const;
@@ -135,7 +135,7 @@ public:
     QXmppConfiguration::NonSASLAuthMechanism Q_DECL_DEPRECATED getNonSASLAuthMechanism() const;
     QXmppConfiguration::SASLAuthMechanism Q_DECL_DEPRECATED getSASLAuthMechanism() const;
     QNetworkProxy Q_DECL_DEPRECATED getNetworkProxy() const;
-// obsolete end
+    /// \endcond
 
 private:
     QString m_host;
diff --git a/source/QXmppIq.h b/source/QXmppIq.h
index deb0af02..d38b5da3 100644
--- a/source/QXmppIq.h
+++ b/source/QXmppIq.h
@@ -33,15 +33,20 @@
 // for an explanation.
 #include <QXmlStreamWriter>
 
+/// \brief The QXmppIq packet is the base class for all IQs.
+///
+/// \ingroup Stanzas
+
 class QXmppIq : public QXmppStanza
 {
 public:
+    /// This enum describes the type of IQ.
     enum Type
     {
-        Error = 0,
-        Get,
-        Set,
-        Result
+        Error = 0,  ///< Error response.
+        Get,        ///< Get request.
+        Set,        ///< Set request.
+        Result      ///< Result.
     };
 
     QXmppIq(QXmppIq::Type type = QXmppIq::Get);
@@ -54,7 +59,9 @@ public:
     void toXml(QXmlStreamWriter *writer) const;
 
     // deprecated accessors, use the form without "get" instead
+    /// \cond
     QXmppIq::Type Q_DECL_DEPRECATED getType() const;
+    /// \endcond
 
 protected:
     virtual void parseElementFromChild(const QDomElement &element);
diff --git a/source/QXmppJingleIq.h b/source/QXmppJingleIq.h
index 6b377dd8..94639a9c 100644
--- a/source/QXmppJingleIq.h
+++ b/source/QXmppJingleIq.h
@@ -115,9 +115,10 @@ private:
     QString m_type;
 };
 
-/// The QXmppJingleIq represent an IQ used for initiating media sessions
-/// as specified by XEP-0166: Jingle.
+/// \brief The QXmppJingleIq class represents an IQ used for initiating media
+/// sessions as specified by XEP-0166: Jingle.
 ///
+/// \ingroup Stanzas
 
 class QXmppJingleIq : public QXmppIq
 {
@@ -140,6 +141,8 @@ public:
         TransportReplace,
     };
 
+    /// \internal
+    ///
     /// The QXmppJingleIq::Content class represents the "content" element of a
     /// QXmppJingleIq.
 
@@ -192,6 +195,8 @@ public:
         QList<QXmppJingleCandidate> m_transportCandidates;
     };
 
+    /// \internal
+    ///
     /// The QXmppJingleIq::Reason class represents the "reason" element of a
     /// QXmppJingleIq.
 
diff --git a/source/QXmppLogger.cpp b/source/QXmppLogger.cpp
index 3d8a327e..ed4b9e89 100644
--- a/source/QXmppLogger.cpp
+++ b/source/QXmppLogger.cpp
@@ -102,11 +102,6 @@ void QXmppLogger::log(QXmppLogger::MessageType type, const QString& str)
     }
 }
 
-QXmppLogger::LoggingType QXmppLogger::getLoggingType()
-{
-    return m_loggingType;
-}
-
 void QXmppLogger::setLogFilePath(const QString& logFilePath)
 {
     m_logFilePath = logFilePath;
diff --git a/source/QXmppLogger.h b/source/QXmppLogger.h
index e21c426d..7111efe2 100644
--- a/source/QXmppLogger.h
+++ b/source/QXmppLogger.h
@@ -63,9 +63,6 @@ public:
     void setLogFilePath(const QString&);
     QString logFilePath();
 
-    // deprecated accessors, use the form without "get" instead
-    QXmppLogger::LoggingType Q_DECL_DEPRECATED getLoggingType();
-
 public slots:
     void log(QXmppLogger::MessageType type, const QString& str);
 
diff --git a/source/QXmppMessage.h b/source/QXmppMessage.h
index 08751821..60bbad60 100644
--- a/source/QXmppMessage.h
+++ b/source/QXmppMessage.h
@@ -28,6 +28,11 @@
 #include <QDateTime>
 #include "QXmppStanza.h"
 
+/// \brief The QXmppMessage class represents an XMPP message.
+///
+/// \ingroup Stanzas
+///
+
 class QXmppMessage : public QXmppStanza
 {
 public:
@@ -85,11 +90,13 @@ public:
     void toXml(QXmlStreamWriter *writer) const;
 
     // deprecated accessors, use the form without "get" instead
+    /// \cond
     QXmppMessage::Type Q_DECL_DEPRECATED getType() const;
     QXmppMessage::State Q_DECL_DEPRECATED getState() const;
     QString Q_DECL_DEPRECATED getBody() const;
     QString Q_DECL_DEPRECATED getSubject() const;
     QString Q_DECL_DEPRECATED getThread() const;
+    /// \endcond
 
 private:
     QString getTypeStr() const;
diff --git a/source/QXmppMucIq.h b/source/QXmppMucIq.h
index 6efa0c22..4c661188 100644
--- a/source/QXmppMucIq.h
+++ b/source/QXmppMucIq.h
@@ -32,6 +32,7 @@
 ///
 /// It is used to get or modify room memberships.
 ///
+/// \ingroup Stanzas
 
 class QXmppMucAdminIq : public QXmppIq
 {
diff --git a/source/QXmppPresence.cpp b/source/QXmppPresence.cpp
index 4ff02c00..e4066c0a 100644
--- a/source/QXmppPresence.cpp
+++ b/source/QXmppPresence.cpp
@@ -323,7 +323,7 @@ void QXmppPresence::Status::toXml(QXmlStreamWriter *xmlWriter) const
         helperToXmlAddNumberElement(xmlWriter, "priority", m_priority);
 }
 
-// obsolete start
+/// \cond
 
 QXmppPresence::Type QXmppPresence::getType() const
 {
@@ -355,4 +355,4 @@ int QXmppPresence::Status::getPriority() const
     return m_priority;
 }
 
-// obsolete end
+/// \endcond
diff --git a/source/QXmppPresence.h b/source/QXmppPresence.h
index 17c804a7..dce46413 100644
--- a/source/QXmppPresence.h
+++ b/source/QXmppPresence.h
@@ -27,6 +27,9 @@
 
 #include "QXmppStanza.h"
 
+/// \brief The QXmppPresence class represents an XMPP presence stanza.
+///
+/// \ingroup Stanzas
 class QXmppPresence : public QXmppStanza
 {
 public:
@@ -71,12 +74,12 @@ public:
         void parse(const QDomElement &element);
         void toXml(QXmlStreamWriter *writer) const;
 
-// deprecated accessors, use the form without "get" instead
-// obsolete start
+        // deprecated accessors, use the form without "get" instead
+        /// \cond
         int Q_DECL_DEPRECATED getPriority() const;
         QString Q_DECL_DEPRECATED getStatusText() const;
         QXmppPresence::Status::Type Q_DECL_DEPRECATED getType() const;
-// obsolete end
+        /// \endcond
 
     private:
         QString getTypeStr() const;
@@ -101,12 +104,12 @@ public:
     void parse(const QDomElement &element);
     void toXml(QXmlStreamWriter *writer) const;
 
-// deprecated accessors, use the form without "get" instead
-// obsolete start
+    // deprecated accessors, use the form without "get" instead
+    /// \cond
     QXmppPresence::Type Q_DECL_DEPRECATED getType() const;
     QXmppPresence::Status Q_DECL_DEPRECATED & getStatus();
     const QXmppPresence::Status Q_DECL_DEPRECATED & getStatus() const;
-// obsolete end
+    /// \endcond
 
 private:
     QString getTypeStr() const;
diff --git a/source/QXmppRoster.h b/source/QXmppRoster.h
index 2e602b6f..d6d4f1a5 100644
--- a/source/QXmppRoster.h
+++ b/source/QXmppRoster.h
@@ -73,15 +73,19 @@ public:
     bool isRosterReceived();
     QStringList getRosterBareJids() const;
     QXmppRoster::QXmppRosterEntry getRosterEntry(const QString& bareJid) const;
-    QMap<QString, QXmppRoster::QXmppRosterEntry> Q_DECL_DEPRECATED getRosterEntries() const;
     
     QStringList getResources(const QString& bareJid) const;
-    QMap<QString, QMap<QString, QXmppPresence> > Q_DECL_DEPRECATED getAllPresences() const;
     QMap<QString, QXmppPresence> getAllPresencesForBareJid(
             const QString& bareJid) const;
     QXmppPresence getPresence(const QString& bareJid,
                               const QString& resource) const;
 
+
+    /// \cond
+    QMap<QString, QXmppRoster::QXmppRosterEntry> Q_DECL_DEPRECATED getRosterEntries() const;
+    QMap<QString, QMap<QString, QXmppPresence> > Q_DECL_DEPRECATED getAllPresences() const;
+    /// \endcond
+
 signals:
     /// This signal is emitted when the Roster IQ is received after a successful
     /// connection.
diff --git a/source/QXmppRosterIq.h b/source/QXmppRosterIq.h
index f81ce7c5..695a4bbe 100644
--- a/source/QXmppRosterIq.h
+++ b/source/QXmppRosterIq.h
@@ -30,6 +30,10 @@
 #include <QList>
 #include <QSet>
 
+/// \brief The QXmppRosterIq class represents a roster IQ.
+///
+/// \ingroup Stanzas
+
 class QXmppRosterIq : public QXmppIq
 {
 public:
@@ -68,12 +72,14 @@ public:
         void parse(const QDomElement &element);
         void toXml(QXmlStreamWriter *writer) const;
         
-// deprecated accessors, use the form without "get" instead
+        // deprecated accessors, use the form without "get" instead
+        /// \cond
         SubscriptionType Q_DECL_DEPRECATED getSubscriptionType() const;
         QString Q_DECL_DEPRECATED getName() const;
         QString Q_DECL_DEPRECATED getSubscriptionStatus() const;
         QString Q_DECL_DEPRECATED getBareJid() const;
         QSet<QString> Q_DECL_DEPRECATED getGroups() const;
+        /// \endcond
 
     private:
         QString getSubscriptionTypeStr() const;
@@ -92,8 +98,10 @@ public:
 
     static bool isRosterIq(const QDomElement &element);
 
-// deprecated accessors, use the form without "get" instead
+    // deprecated accessors, use the form without "get" instead
+    /// \cond
     QList<Item> Q_DECL_DEPRECATED getItems() const;
+    /// \endcond
 
 protected:
     void parseElementFromChild(const QDomElement &element);
diff --git a/source/QXmppStanza.h b/source/QXmppStanza.h
index 8eb8dd7b..3c0bdc63 100644
--- a/source/QXmppStanza.h
+++ b/source/QXmppStanza.h
@@ -35,6 +35,12 @@
 // for an explanation.
 #include <QXmlStreamWriter>
 
+/// \defgroup Stanzas
+
+/// \brief The QXmppStanza class is the base class for all XMPP stanzas.
+///
+/// \ingroup Stanzas
+
 class QXmppStanza : public QXmppPacket
 {
 public:
@@ -99,10 +105,12 @@ public:
         void toXml(QXmlStreamWriter *writer) const;
 
         // deprecated accessors, use the form without "get" instead
+        /// \cond
         int Q_DECL_DEPRECATED getCode() const;
         QString Q_DECL_DEPRECATED getText() const;
         Condition Q_DECL_DEPRECATED getCondition() const;
         Type Q_DECL_DEPRECATED getType() const;
+        /// \endcond
 
     private:
         QString getConditionStr() const;
@@ -142,11 +150,13 @@ public:
     bool isErrorStanza();
 
     // deprecated accessors, use the form without "get" instead
+    /// \cond
     QString Q_DECL_DEPRECATED getTo() const;  
     QString Q_DECL_DEPRECATED getFrom() const;
     QString Q_DECL_DEPRECATED getId() const;    
     QString Q_DECL_DEPRECATED getLang() const;    
     QXmppStanza::Error Q_DECL_DEPRECATED getError() const;
+    /// \endcond
 
 protected:
     void generateAndSetNextId();
diff --git a/source/QXmppTransferManager.cpp b/source/QXmppTransferManager.cpp
index cfc4a491..7f5a47b2 100644
--- a/source/QXmppTransferManager.cpp
+++ b/source/QXmppTransferManager.cpp
@@ -172,7 +172,7 @@ QXmppTransferJob::Direction QXmppTransferJob::direction() const
     return m_direction;
 }
 
-/// Returns the last error that was encoutered.
+/// Returns the last error that was encountered.
 ///
 
 QXmppTransferJob::Error QXmppTransferJob::error() const
@@ -180,11 +180,17 @@ QXmppTransferJob::Error QXmppTransferJob::error() const
     return m_error;
 }
 
+/// Returns the remote party's JID.
+///
+
 QString QXmppTransferJob::jid() const
 {
     return m_jid;
 }
 
+/// Returns meta-data about the file being transfered.
+///
+
 QXmppTransferFileInfo QXmppTransferJob::fileInfo() const
 {
     return m_fileInfo;
@@ -210,16 +216,25 @@ qint64 QXmppTransferJob::fileSize() const
     return m_fileInfo.size();
 }
 
+/// Returns the job's transfer method.
+///
+
 QXmppTransferJob::Method QXmppTransferJob::method() const
 {
     return m_method;
 }
 
+/// Returns the job's session identifier.
+///
+
 QString QXmppTransferJob::sid() const
 {
     return m_sid;
 }
 
+/// Returns the job's state.
+///
+
 QXmppTransferJob::State QXmppTransferJob::state() const
 {
     return m_state;
diff --git a/source/QXmppTransferManager.h b/source/QXmppTransferManager.h
index 59fba3c9..e248ed1b 100644
--- a/source/QXmppTransferManager.h
+++ b/source/QXmppTransferManager.h
@@ -80,12 +80,14 @@ class QXmppTransferJob : public QObject
     Q_OBJECT
 
 public:
+    /// This enum is used to describe the direction of a transfer job.
     enum Direction
     {
         IncomingDirection, ///< The file is being received.
         OutgoingDirection, ///< The file is being sent.
     };
 
+    /// This enum is used to describe the type of error encountered by a transfer job.
     enum Error
     {
         NoError = 0,      ///< No error occured.
@@ -95,6 +97,7 @@ public:
         ProtocolError,    ///< An error was encountered in the file transfer protocol.
     };
 
+    /// This enum is used to describe a transfer method.
     enum Method
     {
         NoMethod = 0,     ///< No transfer method.
@@ -104,12 +107,13 @@ public:
     };
     Q_DECLARE_FLAGS(Methods, Method)
 
+    /// This enum is used to describe the state of a transfer job.
     enum State
     {
-        OfferState = 0,
-        StartState = 1,
-        TransferState = 2,
-        FinishedState = 3,
+        OfferState = 0,    ///< The transfer is being offered to the remote party.
+        StartState = 1,    ///< The transfer is being connected.
+        TransferState = 2, ///< The transfer is ongoing.
+        FinishedState = 3, ///< The transfer is finished.
     };
 
     void abort();
@@ -226,6 +230,10 @@ signals:
     /// To accept the transfer job, call the job's QXmppTransferJob::accept() method.
     /// To refuse the transfer job, call the job's QXmppTransferJob::abort() method.
     void fileReceived(QXmppTransferJob *offer);
+
+    /// This signal is emitted whenever a transfer job is finished.
+    ///
+    /// \sa QXmppTransferJob::finished()
     void finished(QXmppTransferJob *job);
 
     /// This signal is emitted to send logging messages.
diff --git a/source/QXmppVCard.h b/source/QXmppVCard.h
index ad259854..db1da9e5 100644
--- a/source/QXmppVCard.h
+++ b/source/QXmppVCard.h
@@ -56,13 +56,13 @@ public:
     QImage photoAsImage() const;
     const QByteArray& photo() const;
 
-// deprecated accessors, use the form without "get" instead
-// obsolete start
+    // deprecated accessors, use the form without "get" instead
+    /// \cond
     QString Q_DECL_DEPRECATED getFullName() const;
     QString Q_DECL_DEPRECATED getNickName() const;
     QImage Q_DECL_DEPRECATED getPhotoAsImage() const;
     const QByteArray Q_DECL_DEPRECATED & getPhoto() const;
-// obsolete end
+    /// \endcond
 
 protected:
     void parseElementFromChild(const QDomElement&);
diff --git a/source/QXmppVersionIq.h b/source/QXmppVersionIq.h
index dfe5edcd..93d91cbd 100644
--- a/source/QXmppVersionIq.h
+++ b/source/QXmppVersionIq.h
@@ -26,8 +26,10 @@
 
 #include "QXmppIq.h"
 
-/// XEP-0092: Software Version
-/// http://xmpp.org/extensions/xep-0092.html
+/// \brief The QXmppVersionIq class represents an IQ for conveying a software
+/// version as defined by XEP-0092: Software Version.
+///
+/// \ingroup Stanzas
 
 class QXmppVersionIq : public QXmppIq
 {