Doc update.

Change-Id: Ibb7b814016ab352d57ddf415d52ad73d3229de35
Reviewed-by: Wolfgang Beck <wolfgang.beck@nokia.com>

4 files changed, 106 insertions, 36 deletions

diff --git a/doc/doc.pri b/doc/doc.pri
index 41457fe..3b3bd48 100644
--- a/doc/doc.pri
+++ b/doc/doc.pri
@@ -5,3 +5,5 @@ docs_target.commands = qdoc $$PWD/logger.qdocconf
 
 QMAKE_EXTRA_TARGETS = docs_target
 QMAKE_CLEAN += "-r $$PWD/html"
+
+OTHER_FILES += $$PWD/src/*.qdoc
diff --git a/doc/src/index.qdoc b/doc/src/index.qdoc
index e8dbf6d..7e9a32b 100644
--- a/doc/src/index.qdoc
+++ b/doc/src/index.qdoc
@@ -64,17 +64,13 @@
 
     First you need to add the QLogger library dependency to your application:
 
-    LIBS += -lQtLogger
-
-    or use
-
-    QT+= logger
+    QT += logger
 
     In your application you need to include the QLogger header:
 
-    #include <QtLogger/QtLogger>
+    #include <qlogger.h>
 
-    Note: qDebug, qWarning and qCritical getting redefined in this header so make sure that the QLogger header gets included after qlogging.h.
+    Note: qDebug, qWarning and qCritical are re-defined by this header.
 
     \section2 Creating Logging Rules
     \target logging_rules
@@ -125,26 +121,22 @@
     \endtable
 
 
-    The logging rule file can be defined by using the environment variable QT_LOGGING_CONFIG.
-    The application developer can set the rule file by using:
-
-
-    qSetLoggingRulesFile(const QString &path)
-
-
-    or by defining a QByteArray containing the rules and call:
-
+    The logging rule file can be defined by using the environment variable \l QT_LOGGING_CONFIG.
+    The application developer can set the rule file by using \l qSetLoggingRulesFile() or can
+    set the rules directly using \l qSetLoggingRules().
 
-    qSetLoggingRules(const QByteArray &configcontent)
+    If there is no configuration available, the \l {Default settings} will be used.
 
+    \section2 QT_LOGGING_CONFIG
 
-    If there is no configuration available logging will not be performed.
-    Note: QT_LOGGING_CONFIG will overwrite the qSetLoggingRulesFile and qSetLoggingRules calls.
+    The QT_LOGGING_CONFIG environment variable overrides both qSetLoggingRulesFile() and
+    qSetLoggingRules() if it points to a file.
 
+    If QT_LOGGING_CONFIG is relative, QStandardPaths::writeableLocation(QStandardPaths::ConfigLocation) will be prepended.
 
     \section2 Logging usage in your project
 
-    Qt provides a macro to create your logging Categories:
+    Qt provides the \l QT_LOG_CATEGORY() macro to create your logging Categories:
 
     \snippet logger/main.cpp 1
 
@@ -165,28 +157,25 @@
 
     In this example the configuration file "mylogging.cfg" is in the current directory.
 
-    A category logging can be done by using the qCDebug(<category>), qCWarning(<category>) or the qCCritical(<category>) macro.
+    For category-based logging statements, you need to use the \l qCDebug(), \l qCWarning() and \l qCCritical() macros.
 
     \snippet logger/main.cpp 3
 
     \section1 Default settings
-    If there is no logging rules defined "debug" subcategories are disabled but "warning" and "critical" are enabled.
 
+    The defaults are as follows.
 
+    \table
+    \header \li Statement \li Default
+    \row \li qDebug \li Enabled
+    \row \li qWarning \li Enabled
+    \row \li qCritical \li Enabled
+    \row \li qCDebug \li Disabled
+    \row \li qCWarning \li Enabled
+    \row \li qCCritical \li Enabled
+    \endtable
 
-    \section1 Functions
-
-
-    \section2
-    qSetLoggingRules(const QByteArray &rules)
-
-    Set the logging rules with the given \a rules byte array.
-
-
-    \section2
-    qSetLoggingRulesFile(const QString &path)
+    In other words, only \l qCDebug() statements are hidden by default.
 
-    Set the config file with the given \a path which contains the logging rules for category logging.
-    The parameter \a path can contain only the file name.
-    In this case the standard path for configuration files QStandardPaths will be used.
+    \sa QLogging
 */
diff --git a/src/logger/qlogger.cpp b/src/logger/qlogger.cpp
index 196b973..539c523 100644
--- a/src/logger/qlogger.cpp
+++ b/src/logger/qlogger.cpp
@@ -131,6 +131,19 @@ namespace QLoggingCategories
     }
 }
 
+/*!
+    \namespace QLogging
+*/
+
+/*!
+    \relates QLogging
+    Load logging rules from \a path.
+
+    If \a path is relative, QStandardPaths::writeableLocation(QStandardPaths::ConfigLocation) will be prepended.
+
+    Note that if the QT_LOGGING_CONFIG environment variables points to a file, this function does nothing.
+    \sa QT_LOGGING_CONFIG
+*/
 void qSetLoggingRulesFile(const QString &path)
 {
     if (gEnvironment == EnvironmentNotChecked) checkEnvironment();
@@ -140,6 +153,16 @@ void qSetLoggingRulesFile(const QString &path)
         qLogging()->setLoggingRulesFile(config);
 }
 
+/*!
+    \relates QLogging
+    Set logging \a rules directly.
+
+    This is primarily intended for applications that wish to provide runtime control of their
+    logging rather than relying on the user providing a configuration file.
+
+    Note that if the QT_LOGGING_CONFIG environment variables points to a file, this function does nothing.
+    \sa QT_LOGGING_CONFIG
+*/
 void qSetLoggingRules(const QByteArray &rules)
 {
     if (gEnvironment == EnvironmentNotChecked) checkEnvironment();
@@ -149,6 +172,57 @@ void qSetLoggingRules(const QByteArray &rules)
 }
 
 /*!
+    \relates QLogging
+    \macro qCDebug(cat)
+    Works like qDebug() but only prints out if \a cat has been enabled.
+    \code
+    qCDebug(CAT) << "my message";
+    \endcode
+    \sa QT_LOG_CATEGORY(), {Creating Logging Rules}
+*/
+
+/*!
+    \relates QLogging
+    \macro qCWarning(cat)
+    Works like qWarning() and can be disabled with \a cat.
+    \code
+    qCWarning(CAT) << "my message";
+    \endcode
+    \sa QT_LOG_CATEGORY(), {Creating Logging Rules}
+*/
+
+/*!
+    \relates QLogging
+    \macro qCCritical(cat)
+    Works like qCritical() and can be disabled with \a cat.
+    \code
+    qCCritical(CAT) << "my message";
+    \endcode
+    \sa QT_LOG_CATEGORY(), {Creating Logging Rules}
+*/
+
+/*!
+    \relates QLogging
+    \macro QT_LOG_CATEGORY(cat, identifier)
+    Registers a logging category with local identifier \a cat and complete identifier \a identifier.
+
+    This macro must be used outside of a class or method.
+    \sa {Logging usage in your project}
+*/
+
+
+
+
+
+
+
+
+
+
+
+
+
+/*!
     \internal
     QLoggingPrivate constructor
  */
diff --git a/src/logger/qlogger.h b/src/logger/qlogger.h
index 400dccc..ce06201 100644
--- a/src/logger/qlogger.h
+++ b/src/logger/qlogger.h
@@ -66,6 +66,11 @@ namespace QLoggingCategories {
     Q_LOGGER_EXPORT bool isEnabled();
 }
 
+// This is here so that QDoc has something to attach the functions
+// and macros to.
+namespace QLogging {
+}
+
 Q_LOGGER_EXPORT void qSetLoggingRules(const QByteArray &rules);
 Q_LOGGER_EXPORT void qSetLoggingRulesFile(const QString &path);