improve code documentation

5 files changed, 87 insertions, 35 deletions

diff --git a/source/QXmppMessage.cpp b/source/QXmppMessage.cpp
index 97f4d402..b5b7f8fa 100644
--- a/source/QXmppMessage.cpp
+++ b/source/QXmppMessage.cpp
@@ -54,6 +54,26 @@ QXmppMessage::~QXmppMessage()
 
 }
 
+/// Returns the message's body.
+///
+
+QString QXmppMessage::body() const
+{
+    return m_body;
+}
+
+/// Sets the message's body.
+///
+/// \param body
+
+void QXmppMessage::setBody(const QString& body)
+{
+    m_body = body;
+}
+
+/// Returns the message's type.
+///
+
 QXmppMessage::Type QXmppMessage::type() const
 {
     return m_type;
@@ -79,6 +99,10 @@ QString QXmppMessage::getTypeStr() const
     }
 }
 
+/// Sets the message's type.
+///
+/// \param type
+
 void QXmppMessage::setType(QXmppMessage::Type type)
 {
     m_type = type;
@@ -125,29 +149,34 @@ void QXmppMessage::setTypeFromStr(const QString& str)
     }
 }
 
-/// Returns the message timestamp (if any).
-///
-/// XEP-0091: Legacy Delayed Delivery
+/// Returns the message's timestamp (if any).
 
 QDateTime QXmppMessage::stamp() const
 {
     return m_stamp;
 }
 
-/// Sets the message timestamp.
+/// Sets the message's timestamp.
 ///
-/// XEP-0091: Legacy Delayed Delivery
+/// \param stamp
 
 void QXmppMessage::setStamp(const QDateTime &stamp)
 {
     m_stamp = stamp;
 }
 
+/// Returns the message's chat state.
+///
+
 QXmppMessage::State QXmppMessage::state() const
 {
     return m_state;
 }
 
+/// Sets the message's chat state.
+///
+/// \param state
+
 void QXmppMessage::setState(QXmppMessage::State state)
 {
     m_state = state;
@@ -256,31 +285,34 @@ void QXmppMessage::toXml(QXmlStreamWriter *xmlWriter) const
     xmlWriter->writeEndElement();
 }
 
-QString QXmppMessage::body() const
-{
-    return m_body;
-}
-
-void QXmppMessage::setBody(const QString& body)
-{
-    m_body = body;
-}
+/// Returns the message's subject.
+///
 
 QString QXmppMessage::subject() const
 {
     return m_subject;
 }
 
-void QXmppMessage::setSubject(const QString& sub)
+/// Sets the message's subject.
+///
+/// \param subject
+
+void QXmppMessage::setSubject(const QString& subject)
 {
-    m_subject = sub;
+    m_subject = subject;
 }
 
+/// Returns the message's thread.
+
 QString QXmppMessage::thread() const
 {
     return m_thread;
 }
 
+/// Sets the message's thread.
+///
+/// \param thread
+
 void QXmppMessage::setThread(const QString& thread)
 {
     m_thread = thread;
diff --git a/source/QXmppMessage.h b/source/QXmppMessage.h
index 60bbad60..bf258f53 100644
--- a/source/QXmppMessage.h
+++ b/source/QXmppMessage.h
@@ -36,6 +36,7 @@
 class QXmppMessage : public QXmppStanza
 {
 public:
+    /// This enum described a message type.
     enum Type
     {
         Error = 0,
@@ -45,8 +46,8 @@ public:
         Headline
     };
 
-    // XEP-0085 : Chat State Notifications
-    // http://xmpp.org/extensions/xep-0085.html
+    /// This enum describes a chat state as defined by 
+    /// XEP-0085 : Chat State Notifications.
     enum State
     {
         None = 0,
@@ -57,19 +58,12 @@ public:
         Paused,
     };
 
-    /// Type of the message timestamp.
-    enum StampType
-    {
-        LegacyDelayedDelivery,  ///< XEP-0091: Legacy Delayed Delivery
-        DelayedDelivery,        ///< XEP-0203: Delayed Delivery
-    };
-
     QXmppMessage(const QString& from = "", const QString& to = "",
                  const QString& body = "", const QString& thread = "");
     ~QXmppMessage();
     
-    QXmppMessage::Type type() const;
-    void setType(QXmppMessage::Type);
+    QString body() const;
+    void setBody(const QString&);
 
     QDateTime stamp() const;
     void setStamp(const QDateTime &stamp);
@@ -77,20 +71,20 @@ public:
     QXmppMessage::State state() const;
     void setState(QXmppMessage::State);
 
-    QString body() const;
-    void setBody(const QString&);
-
     QString subject() const;
     void setSubject(const QString&);
 
     QString thread() const;
     void setThread(const QString&);
 
+    QXmppMessage::Type type() const;
+    void setType(QXmppMessage::Type);
+
+    /// \cond
     void parse(const QDomElement &element);
     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;
@@ -99,6 +93,13 @@ public:
     /// \endcond
 
 private:
+    /// This enum describe a type of message timestamp.
+    enum StampType
+    {
+        LegacyDelayedDelivery,  ///< XEP-0091: Legacy Delayed Delivery
+        DelayedDelivery,        ///< XEP-0203: Delayed Delivery
+    };
+
     QString getTypeStr() const;
     void setTypeFromStr(const QString&);
 
diff --git a/source/QXmppPresence.h b/source/QXmppPresence.h
index dce46413..0e9d0fe6 100644
--- a/source/QXmppPresence.h
+++ b/source/QXmppPresence.h
@@ -71,11 +71,11 @@ public:
         int priority() const;
         void setPriority(int);
 
+        /// \cond
         void parse(const QDomElement &element);
         void toXml(QXmlStreamWriter *writer) const;
 
         // 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;
diff --git a/source/QXmppStanza.cpp b/source/QXmppStanza.cpp
index 22f6a2e9..a311d82f 100644
--- a/source/QXmppStanza.cpp
+++ b/source/QXmppStanza.cpp
@@ -304,31 +304,50 @@ QXmppStanza::~QXmppStanza()
 {
 }
 
+/// Returns the stanza's recipient JID.
+///
+
 QString QXmppStanza::to() const
 {
     return m_to;
 }
 
+/// Sets the stanza's recipient JID.
+///
+/// \param to
+
 void QXmppStanza::setTo(const QString& to)  
 {
     m_to = to;
 }
 
+/// Returns the stanza's sender JID.
+
 QString QXmppStanza::from() const
 {
     return m_from;
 }
 
+/// Sets the stanza's sender JID.
+///
+/// \param from
+
 void QXmppStanza::setFrom(const QString& from)
 {
     m_from = from;
 }
 
+/// Returns the stanza's identifier.
+
 QString QXmppStanza::id() const    
 {
     return m_id;
 }
 
+/// Sets the stanza's identifier.
+///
+/// \param id
+
 void QXmppStanza::setId(const QString& id)    
 {
     m_id = id;
diff --git a/source/QXmppStanza.h b/source/QXmppStanza.h
index 3c0bdc63..ea87a6c6 100644
--- a/source/QXmppStanza.h
+++ b/source/QXmppStanza.h
@@ -101,11 +101,11 @@ public:
         // FIXME : remove this once is gone
         bool isValid();
 
+        /// \cond
         void parse(const QDomElement &element);
         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;
@@ -146,21 +146,21 @@ public:
     QXmppElementList extensions() const;
     void setExtensions(const QXmppElementList &elements);
 
+    /// \cond
     // FIXME : why is this needed?
     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();
     void parse(const QDomElement &element);
+    /// \endcond
 
 private:
     static uint s_uniqeIdNo;