improve code documentation

3 files changed, 67 insertions, 24 deletions

diff --git a/source/QXmppClient.h b/source/QXmppClient.h
index 25bdf6b5..f660d437 100644
--- a/source/QXmppClient.h
+++ b/source/QXmppClient.h
@@ -52,6 +52,8 @@ class QXmppVCardManager;
 class QXmppTransferManager;
 class QXmppCallManager;
 
+/// \defgroup Core
+
 /// \defgroup Managers
 
 /// \brief The QXmppClient class is the main class for using QXmpp.
@@ -70,6 +72,7 @@ class QXmppCallManager;
 /// For removing QXmpp dependency in QtGui, use DEFINE = QXMPP_NO_GUI
 /// in the source.pro file and build as usual
 ///
+/// \ingroup Core
 
 class QXmppClient : public QObject
 {
diff --git a/source/QXmppLogger.cpp b/source/QXmppLogger.cpp
index ed4b9e89..7659d889 100644
--- a/source/QXmppLogger.cpp
+++ b/source/QXmppLogger.cpp
@@ -1,8 +1,9 @@
 /*
  * Copyright (C) 2008-2010 Manjeet Dahiya
  *
- * Author:
+ * Authors:
  *	Manjeet Dahiya
+ *	Jeremy Lainé
  *
  * Source:
  *	http://code.google.com/p/qxmpp
@@ -50,12 +51,19 @@ static const char *typeName(QXmppLogger::MessageType type)
     }
 }
 
+/// Constructs a new QXmppLogger.
+///
+/// \param parent
+
 QXmppLogger::QXmppLogger(QObject *parent)
     : QObject(parent), m_loggingType(QXmppLogger::NoLogging),
     m_logFilePath("QXmppClientLog.log")
 {
 }
 
+/// Returns the default logger.
+///
+
 QXmppLogger* QXmppLogger::getLogger()
 {
     if(!m_logger)
@@ -67,17 +75,29 @@ QXmppLogger* QXmppLogger::getLogger()
     return m_logger;
 }
 
-void QXmppLogger::setLoggingType(QXmppLogger::LoggingType log)
-{
-    m_loggingType = log;
-}
+/// Returns the handler for logging messages.
+///
 
 QXmppLogger::LoggingType QXmppLogger::loggingType()
 {
     return m_loggingType;
 }
 
-void QXmppLogger::log(QXmppLogger::MessageType type, const QString& str)
+/// Sets the handler for logging messages.
+///
+/// \param type
+
+void QXmppLogger::setLoggingType(QXmppLogger::LoggingType type)
+{
+    m_loggingType = type;
+}
+
+/// Add a logging message.
+///
+/// \param type
+/// \param text
+
+void QXmppLogger::log(QXmppLogger::MessageType type, const QString& text)
 {
     switch(m_loggingType)
     {
@@ -88,26 +108,37 @@ void QXmppLogger::log(QXmppLogger::MessageType type, const QString& str)
             QTextStream stream(&file);
             stream << QTime::currentTime().toString("hh:mm:ss.zzz") <<
                 " " << typeName(type) << " " <<
-                str << "\n\n";
+                text << "\n\n";
         }
         break;
     case QXmppLogger::StdoutLogging:
-        std::cout << typeName(type) << " " << qPrintable(str) << std::endl;
+        std::cout << typeName(type) << " " << qPrintable(text) << std::endl;
         break;
     case QXmppLogger::SignalLogging:
-        emit message(type, str);
+        emit message(type, text);
         break;
     default:
         break;
     }
 }
 
-void QXmppLogger::setLogFilePath(const QString& logFilePath)
-{
-    m_logFilePath = logFilePath;
-}
+/// Returns the path to which logging messages should be written.
+///
+/// \sa loggingType()
 
 QString QXmppLogger::logFilePath()
 {
     return m_logFilePath;
 }
+
+/// Sets the path to which logging messages should be written.
+///
+/// \param path
+///
+/// \sa setLoggingType()
+
+void QXmppLogger::setLogFilePath(const QString &path)
+{
+    m_logFilePath = logFilePath;
+}
+
diff --git a/source/QXmppLogger.h b/source/QXmppLogger.h
index 7111efe2..a81dba4a 100644
--- a/source/QXmppLogger.h
+++ b/source/QXmppLogger.h
@@ -27,24 +27,32 @@
 
 #include <QObject>
 
+/// \brief The QXmppLogger class represents a sink for logging messages. 
+///
+/// \ingroup Core
+
 class QXmppLogger : public QObject
 {
     Q_OBJECT
 
 public:
+    /// This enum describes how log message are handled.
     enum LoggingType
     {
-        NoLogging = 0,  ///< Log messages are discarded
-        FileLogging,     ///< Log messages are written to a file
-        StdoutLogging,   ///< Log messages are written to the standard output
-        SignalLogging,   ///< Log messages are emitted as a signal
+        NoLogging = 0,      ///< Log messages are discarded
+        FileLogging = 1,    ///< Log messages are written to a file
+        StdoutLogging = 2,  ///< Log messages are written to the standard output
+        SignalLogging = 4,  ///< Log messages are emitted as a signal
 
         // Deprecated
-        NONE = 0, ///< DEPRECATED Log messages are discarded
-        FILE,     ///< DEPRECATED Log messages are written to a file
-        STDOUT   ///< DEPRECATED Log messages are written to the standard output
+        /// \cond
+        NONE = 0,   ///< DEPRECATED Log messages are discarded
+        FILE = 1,   ///< DEPRECATED Log messages are written to a file
+        STDOUT = 2  ///< DEPRECATED Log messages are written to the standard output
+        /// \endcond
     };
 
+    /// This enum describes a type of log message.
     enum MessageType
     {
         DebugMessage = 0,   ///< Debugging message
@@ -58,16 +66,17 @@ public:
     static QXmppLogger* getLogger();
 
     QXmppLogger::LoggingType loggingType();
-    void setLoggingType(QXmppLogger::LoggingType);
+    void setLoggingType(QXmppLogger::LoggingType type);
 
-    void setLogFilePath(const QString&);
     QString logFilePath();
+    void setLogFilePath(const QString &path);
 
 public slots:
-    void log(QXmppLogger::MessageType type, const QString& str);
+    void log(QXmppLogger::MessageType type, const QString& text);
 
 signals:
-    void message(QXmppLogger::MessageType type, const QString &str);
+    /// This signal is emitted whenever a log message is received.
+    void message(QXmppLogger::MessageType type, const QString &text);
 
 private:
     static QXmppLogger* m_logger;