improve code documentation

6 files changed, 71 insertions, 4 deletions

diff --git a/src/QXmppJingleIq.cpp b/src/QXmppJingleIq.cpp
index da3501df..4538c748 100644
--- a/src/QXmppJingleIq.cpp
+++ b/src/QXmppJingleIq.cpp
@@ -281,46 +281,72 @@ void QXmppJingleIq::Reason::toXml(QXmlStreamWriter *writer) const
     writer->writeEndElement();
 }
 
+/// Constructs a QXmppJingleIq.
+
 QXmppJingleIq::QXmppJingleIq()
     : m_ringing(false)
 {
 }
 
+/// Returns the Jingle IQ's action.
+
 QXmppJingleIq::Action QXmppJingleIq::action() const
 {
     return m_action;
 }
 
+/// Sets the Jingle IQ's action.
+///
+/// \param action
+
 void QXmppJingleIq::setAction(QXmppJingleIq::Action action)
 {
     m_action = action;
 }
 
+/// Returns the session initiator.
+
 QString QXmppJingleIq::initiator() const
 {
     return m_initiator;
 }
 
+/// Sets the session initiator.
+///
+/// \param initiator
+
 void QXmppJingleIq::setInitiator(const QString &initiator)
 {
     m_initiator = initiator;
 }
 
+/// Returns the session responder.
+
 QString QXmppJingleIq::responder() const
 {
     return m_responder;
 }
 
+/// Sets the session responder.
+///
+/// \param responder
+
 void QXmppJingleIq::setResponder(const QString &responder)
 {
     m_responder = responder;
 }
 
+/// Returns the session ID.
+
 QString QXmppJingleIq::sid() const
 {
     return m_sid;
 }
 
+/// Sets the session ID.
+///
+/// \param sid
+
 void QXmppJingleIq::setSid(const QString &sid)
 {
     m_sid = sid;
@@ -332,11 +358,17 @@ bool QXmppJingleIq::isJingleIq(const QDomElement &element)
     return (jingleElement.namespaceURI() == ns_jingle);
 }
 
+/// Returns true if the call is ringing.
+
 bool QXmppJingleIq::ringing() const
 {
     return m_ringing;
 }
 
+/// Set to true if the call is ringing.
+///
+/// \param ringing
+
 void QXmppJingleIq::setRinging(bool ringing)
 {
     m_ringing = ringing;
@@ -756,6 +788,10 @@ void QXmppJinglePayloadType::toXml(QXmlStreamWriter *writer) const
     writer->writeEndElement();
 }
 
+/// Returns true if this QXmppJinglePayloadType and \a other refer to the same payload type.
+///
+/// \param other
+
 bool QXmppJinglePayloadType::operator==(const QXmppJinglePayloadType &other) const
 {
     // FIXME : what to do with m_ptime and m_maxptime?
diff --git a/src/QXmppJingleIq.h b/src/QXmppJingleIq.h
index 677256cf..cce0d8e4 100644
--- a/src/QXmppJingleIq.h
+++ b/src/QXmppJingleIq.h
@@ -78,12 +78,16 @@ private:
 class QXmppJingleCandidate
 {
 public:
+    /// This enum is used to describe a candidate's type.
     enum Type
     {
-        HostType,
-        PeerReflexiveType,
-        ServerReflexiveType,
-        RelayedType,
+        HostType,               ///< Host candidate, a local address/port.
+        PeerReflexiveType,      ///< Peer-reflexive candidate,
+                                ///< the address/port as seen from the peer.
+        ServerReflexiveType,    ///< Server-reflexive candidate,
+                                ///< the address/port as seen by the STUN server
+        RelayedType,            ///< Relayed candidate, a candidate from
+                                ///< a TURN relay.
     };
 
     QXmppJingleCandidate();
@@ -143,6 +147,7 @@ private:
 class QXmppJingleIq : public QXmppIq
 {
 public:
+    /// This enum is used to describe a Jingle action.
     enum Action {
         ContentAccept,
         ContentAdd,
@@ -278,17 +283,25 @@ public:
     QString sid() const;
     void setSid(const QString &sid);
 
+    /// Returns a reference to the IQ's content element.
     Content& content() { return m_content; };
+
+    /// Returns a const reference to the IQ's content element.
     const Content& content() const { return m_content; };
 
+    /// Returns a reference to the IQ's reason element.
     Reason& reason() { return m_reason; };
+
+    /// Returns a const reference to the IQ's reason element.
     const Reason& reason() const { return m_reason; };
 
     // XEP-0167: Jingle RTP Sessions
     bool ringing() const;
     void setRinging(bool ringing);
 
+    /// \cond
     static bool isJingleIq(const QDomElement &element);
+    /// \endcond
 
 protected:
     /// \cond
diff --git a/src/QXmppStream.cpp b/src/QXmppStream.cpp
index 848dc245..428ba119 100644
--- a/src/QXmppStream.cpp
+++ b/src/QXmppStream.cpp
@@ -94,6 +94,9 @@ void QXmppStream::disconnectFromHost()
     }
 }
 
+/// Handles a stream start event, which occurs when the underlying transport
+/// becomes ready (socket connected, encryption started).
+
 void QXmppStream::handleStart()
 {
 }
diff --git a/src/QXmppStream.h b/src/QXmppStream.h
index 525e2cb5..3ce5999d 100644
--- a/src/QXmppStream.h
+++ b/src/QXmppStream.h
@@ -66,7 +66,15 @@ protected:
 
     // Overridable methods
     virtual void handleStart();
+
+    /// Handles an incoming XMPP stanza.
+    ///
+    /// \param element
     virtual void handleStanza(const QDomElement &element) = 0;
+
+    /// Handles an incoming XMPP stream start.
+    ///
+    /// \param element
     virtual void handleStream(const QDomElement &element) = 0;
 
 private slots:
diff --git a/src/QXmppTransferManager.cpp b/src/QXmppTransferManager.cpp
index ad56ccf2..e36bcc7a 100644
--- a/src/QXmppTransferManager.cpp
+++ b/src/QXmppTransferManager.cpp
@@ -422,6 +422,10 @@ bool QXmppTransferJob::writeData(const QByteArray &data)
     return true;
 }
 
+/// Constructs a QXmppTransferManager to handle incoming and outgoing
+/// file transfers.
+///
+/// \param client
 QXmppTransferManager::QXmppTransferManager(QXmppClient *client)
     : m_ibbBlockSize(4096),
     m_proxyOnly(false),
diff --git a/src/QXmppTransferManager.h b/src/QXmppTransferManager.h
index 6584a31f..b08e22c2 100644
--- a/src/QXmppTransferManager.h
+++ b/src/QXmppTransferManager.h
@@ -131,10 +131,13 @@ public:
 
     // XEP-0096 : File transfer
     QXmppTransferFileInfo fileInfo() const;
+
+    /// \cond
     QDateTime fileDate() const;
     QByteArray fileHash() const;
     QString fileName() const;
     qint64 fileSize() const;
+    /// \endcond
 
 signals:
     /// This signal is emitted when an error is encountered while