improve code documentation

5 files changed, 124 insertions, 26 deletions

diff --git a/src/QXmppServerExtension.cpp b/src/QXmppServerExtension.cpp
index c395de3e..81454d70 100644
--- a/src/QXmppServerExtension.cpp
+++ b/src/QXmppServerExtension.cpp
@@ -145,6 +145,10 @@ void QXmppServerExtension::setServer(QXmppServer *server)
     d->server = server;
 }
 
+/// Logs a debugging message.
+///
+/// \param message
+
 void QXmppServerExtension::debug(const QString &message)
 {
     QXmppLogger *logger = server()->logger();
@@ -152,6 +156,10 @@ void QXmppServerExtension::debug(const QString &message)
         logger->log(QXmppLogger::DebugMessage, message);
 }
 
+/// Logs an informational message.
+///
+/// \param message
+
 void QXmppServerExtension::info(const QString &message)
 {
     QXmppLogger *logger = server()->logger();
@@ -159,6 +167,10 @@ void QXmppServerExtension::info(const QString &message)
         logger->log(QXmppLogger::InformationMessage, message);
 }
 
+/// Logs a warning message.
+///
+/// \param message
+
 void QXmppServerExtension::warning(const QString &message)
 {
     QXmppLogger *logger = server()->logger();
diff --git a/src/QXmppServerPlugin.h b/src/QXmppServerPlugin.h
index 6338d3d3..ce9269e9 100644
--- a/src/QXmppServerPlugin.h
+++ b/src/QXmppServerPlugin.h
@@ -29,9 +29,6 @@
 class QXmppServer;
 class QXmppServerExtension;
 
-/// \breif Interface for all QXmppServer plugins.
-///
-
 class QXmppServerPluginInterface
 {
 public:
@@ -48,6 +45,16 @@ class QXmppServerPlugin : public QObject, public QXmppServerPluginInterface
 {
     Q_OBJECT
     Q_INTERFACES(QXmppServerPluginInterface)
+
+public:
+    /// Creates and returns the specified QXmppServerExtension.
+    ///
+    /// \param key The key for the QXmppServerExtension.
+    virtual QXmppServerExtension *create(const QString &key) = 0;
+
+    /// Returns the list of keys supported by this plugin.
+    ///
+    virtual QStringList keys() const = 0;
 };
 
 #endif
diff --git a/src/QXmppStream.cpp b/src/QXmppStream.cpp
index e3d9d737..63dfd843 100644
--- a/src/QXmppStream.cpp
+++ b/src/QXmppStream.cpp
@@ -121,19 +121,31 @@ void QXmppStream::setLogger(QXmppLogger *logger)
                 d->logger, SLOT(log(QXmppLogger::MessageType, QString)));
 }
 
-void QXmppStream::debug(const QString &data)
+/// Logs a debugging message.
+///
+/// \param message
+
+void QXmppStream::debug(const QString &message)
 {
-    emit logMessage(QXmppLogger::DebugMessage, data);
+    emit logMessage(QXmppLogger::DebugMessage, message);
 }
 
-void QXmppStream::info(const QString &data)
+/// Logs an informational message.
+///
+/// \param message
+
+void QXmppStream::info(const QString &message)
 {
-    emit logMessage(QXmppLogger::InformationMessage, data);
+    emit logMessage(QXmppLogger::InformationMessage, message);
 }
 
-void QXmppStream::warning(const QString &data)
+/// Logs a warning message.
+///
+/// \param message
+
+void QXmppStream::warning(const QString &message)
 {
-    emit logMessage(QXmppLogger::WarningMessage, data);
+    emit logMessage(QXmppLogger::WarningMessage, message);
 }
 
 /// Returns true if the stream is connected.
diff --git a/src/QXmppVCard.cpp b/src/QXmppVCard.cpp
index 1ff181a4..9b4b93b2 100644
--- a/src/QXmppVCard.cpp
+++ b/src/QXmppVCard.cpp
@@ -69,81 +69,140 @@ QXmppVCard::QXmppVCard(const QString& jid) : QXmppIq(QXmppIq::Get)
     setTo(jid);
 }
 
+/// Returns the date of birth of the individual associated with the vCard.
+///
+
 QDate QXmppVCard::birthday() const
 {
     return m_birthday;
 }
 
+/// Sets the date of birth of the individual associated with the vCard.
+///
+/// \param birthday
+
 void QXmppVCard::setBirthday(const QDate &birthday)
 {
     m_birthday = birthday;
 }
 
+/// Returns the email address.
+///
+
 QString QXmppVCard::email() const
 {
     return m_email;
 }
 
+/// Sets the email address.
+///
+/// \param email
+
 void QXmppVCard::setEmail(const QString &email)
 {
     m_email = email;
 }
 
+/// Returns the first name.
+///
+
 QString QXmppVCard::firstName() const
 {
     return m_firstName;
 }
 
+/// Sets the first name.
+///
+/// \param firstName
+
 void QXmppVCard::setFirstName(const QString &firstName)
 {
     m_firstName = firstName;
 }
 
+/// Returns the full name.
+///
+
 QString QXmppVCard::fullName() const
 {
     return m_fullName;
 }
 
-void QXmppVCard::setFullName(const QString& str)
+/// Sets the full name.
+///
+/// \param fullName
+
+void QXmppVCard::setFullName(const QString &fullName)
 {
-    m_fullName = str;
+    m_fullName = fullName;
 }
 
+/// Returns the last name.
+///
+
 QString QXmppVCard::lastName() const
 {
     return m_lastName;
 }
 
+/// Sets the last name.
+///
+/// \param lastName
+
 void QXmppVCard::setLastName(const QString &lastName)
 {
     m_lastName = lastName;
 }
 
+/// Returns the middle name.
+///
+
 QString QXmppVCard::middleName() const
 {
     return m_middleName;
 }
 
+/// Sets the middle name.
+///
+/// \param middleName
+
 void QXmppVCard::setMiddleName(const QString &middleName)
 {
     m_middleName = middleName;
 }
 
+/// Returns the nickname.
+///
+
 QString QXmppVCard::nickName() const
 {
     return m_nickName;
 }
 
-void QXmppVCard::setNickName(const QString& str)
+/// Sets the nickname.
+///
+/// \param nickName
+
+void QXmppVCard::setNickName(const QString &nickName)
 {
-    m_nickName = str;
+    m_nickName = nickName;
 }
 
+/// Returns the URL associated with the vCard. It can represent the user's
+/// homepage or a location at which you can find real-time information about
+/// the vCard.
+
 QString QXmppVCard::url() const
 {
     return m_url;
 }
 
+/// Sets the URL associated with the vCard. It can represent the user's
+/// homepage or a location at which you can find real-time information about
+/// the vCard.
+///
+/// \param vCard
+
 void QXmppVCard::setUrl(const QString& url)
 {
     m_url = url;
diff --git a/src/QXmppVCard.h b/src/QXmppVCard.h
index 5f8b9d28..db18f517 100644
--- a/src/QXmppVCard.h
+++ b/src/QXmppVCard.h
@@ -47,14 +47,26 @@ class QXmppVCard : public QXmppIq
 public:
     QXmppVCard(const QString& bareJid = "");
 
+    QDate birthday() const;
     void setBirthday(const QDate &birthday);
+
+    QString email() const;
     void setEmail(const QString&);
+
+    QString firstName() const;
     void setFirstName(const QString&);
+
+    QString fullName() const;
     void setFullName(const QString&);
+
+    QString lastName() const;
     void setLastName(const QString&);
+
+    QString middleName() const;
     void setMiddleName(const QString&);
+
+    QString nickName() const;
     void setNickName(const QString&);
-    void setUrl(const QString&);
 
     QByteArray photo() const;
     void setPhoto(const QByteArray&);
@@ -62,25 +74,21 @@ public:
     QString photoType() const;
     void setPhotoType(const QString &type);
 
-    QDate birthday() const;
-    QString email() const;
-    QString firstName() const;
-    QString fullName() const;
-    QString lastName() const;
-    QString middleName() const;
-    QString nickName() const;
     QString url() const;
+    void setUrl(const QString&);
+
+    static bool isVCard(const QDomElement &element);
 
+    /// \cond
+// deprecated in release 0.3.0, as it drags in a dependency
+// on QtGui, whilst the rest of QXmpp does not require QtGui
 #ifndef QXMPP_NO_GUI
-    QImage photoAsImage() const;
-    void setPhoto(const QImage&);
+    QImage Q_DECL_DEPRECATED photoAsImage() const;
+    void Q_DECL_DEPRECATED setPhoto(const QImage&);
 #endif
 
-    static bool isVCard(const QDomElement &element);
-
 // deprecated accessors, use the form without "get" instead
 // deprecated in release 0.2.0
-    /// \cond
     QString Q_DECL_DEPRECATED getFullName() const;
     QString Q_DECL_DEPRECATED getNickName() const;
     QImage Q_DECL_DEPRECATED getPhotoAsImage() const;