1 files changed, 56 insertions, 31 deletions

diff --git a/src/corelib/io/qloggingcategory.cpp b/src/corelib/io/qloggingcategory.cpp
index 6c5df1e8e7..8d337ec630 100644
--- a/src/corelib/io/qloggingcategory.cpp
+++ b/src/corelib/io/qloggingcategory.cpp
@@ -71,30 +71,36 @@ Q_GLOBAL_STATIC_WITH_ARGS(QLoggingCategory, qtDefaultCategory,
 
     \section1 Checking category configuration
 
-    QLoggingCategory provides a generic \l isEnabled() and message
-    type dependent \l isDebugEnabled(), \l isWarningEnabled(),
-    \l isCriticalEnabled() and \l isTraceEnabled()
-    methods for checking whether the current category is enabled.
+    QLoggingCategory provides \l isDebugEnabled(), \l isWarningEnabled(),
+    \l isCriticalEnabled(), \l isTraceEnabled(), as well as \l isEnabled()
+    to check whether messages for the given message type should be logged.
 
     \note The qCDebug(), qCWarning(), qCCritical(), qCTrace() and
     qCTraceGuard() macros prevent arguments from being evaluated if the
     respective message types are not enabled for the category, so explicit
     checking is not needed:
 
-    \snippet qloggingcategory/main.cpp 3
+    \snippet qloggingcategory/main.cpp 4
 
-    \section1 Default configuration
+    \section1 Default category configuration
 
     In the default configuration \l isWarningEnabled() and \l isCriticalEnabled()
-    will return \c true. By default, \l isDebugEnabled() will return \c true only
+    will return \c true. \l isDebugEnabled() will return \c true only
     for the \c "default" category.
 
-    \section1 Changing configuration
+    \section1 Changing the configuration of a category
+
+    Use either \l setFilterRules() or \l installFilter() to
+    configure categories, for example
+
+    \snippet qloggingcategory/main.cpp 2
+
+    \section1 Printing the category
+
+    Use the \c %{category} place holder to print the category in the default
+    message handler:
 
-    The default configuration can be changed by calling \l setEnabled(). However,
-    this only affects the current category object, not e.g. another object for the
-    same category name. Use either \l setFilterRules() or \l installFilter() to
-    configure categories globally.
+    \snippet qloggingcategory/main.cpp 3
 */
 
 typedef QVector<QTracer *> Tracers;
@@ -117,7 +123,10 @@ QLoggingCategory::QLoggingCategory(const char *category)
       enabledDebug(false),
       enabledWarning(true),
       enabledCritical(true),
-      enabledTrace(false)
+      enabledTrace(false),
+      placeholder1(false),
+      placeholder2(false),
+      placeholder3(false)
 {
     bool isDefaultCategory
             = (category == 0) || (strcmp(category, qtDefaultCategoryName) == 0);
@@ -215,14 +224,12 @@ bool QLoggingCategory::isEnabled(QtMsgType msgtype) const
 /*!
     Changes the message type \a type for the category to \a enable.
 
-    Changes only affect the current QLoggingCategory object, and won't
-    change e.g. the settings of another objects for the same category name.
+    \note Changes only affect the current QLoggingCategory object, and won't
+    change the settings of other objects for the same category name.
+    Use either \l setFilterRules() or \l installFilter() to change the
+    configuration globally.
 
     \note \c QtFatalMsg cannot be changed. It will always return \c true.
-
-    Example:
-
-    \snippet qtracer/ftracer.cpp 5
 */
 void QLoggingCategory::setEnabled(QtMsgType type, bool enable)
 {
@@ -244,12 +251,19 @@ void QLoggingCategory::setEnabled(QtMsgType type, bool enable)
  */
 
 /*!
-    Returns the category \c "default" that is used e.g. by qDebug(), qWarning(),
-    qCritical(), qFatal().
+    Returns a pointer to the global category \c "default" that
+    is used e.g. by qDebug(), qWarning(), qCritical(), qFatal().
+
+    \note The returned pointer may be null during destruction of
+    static objects.
+
+    \note Ownership of the category is not transferred, do not
+    \c delete the returned pointer.
+
  */
-QLoggingCategory &QLoggingCategory::defaultCategory()
+QLoggingCategory *QLoggingCategory::defaultCategory()
 {
-    return *qtDefaultCategory();
+    return qtDefaultCategory();
 }
 
 /*!
@@ -272,6 +286,12 @@ QLoggingCategory &QLoggingCategory::defaultCategory()
     filter is free to change the respective category configuration with
     \l setEnabled().
 
+    The filter might be called concurrently from different threads, and
+    therefore has to be reentrant.
+
+    Example:
+    \snippet qloggingcategory/main.cpp 21
+
     An alternative way of configuring the default filter is via
     \l setFilterRules().
  */
@@ -281,7 +301,6 @@ QLoggingCategory::installFilter(QLoggingCategory::CategoryFilter filter)
     return QLoggingRegistry::instance()->installFilter(filter);
 }
 
-
 /*!
     Configures which categories and message types should be enabled through a
     a set of \a rules.
@@ -296,8 +315,13 @@ QLoggingCategory::installFilter(QLoggingCategory::CategoryFilter filter)
     wildcard symbol at the start and/or the end. The optional \c <type> must
     be either \c debug, \c warning, \c critical, or \c trace.
 
-    The rules might be ignored if a custom category filter is installed with
-    \l installFilter().
+    Example:
+
+    \snippet qloggingcategory/main.cpp 2
+
+    \note The rules might be ignored if a custom category filter is installed
+    with \l installFilter().
+
 */
 void QLoggingCategory::setFilterRules(const QString &rules)
 {
@@ -380,7 +404,7 @@ void QLoggingCategory::setFilterRules(const QString &rules)
 
     The macro expands to code that checks whether
     \l QLoggingCategory::isTraceEnabled() evaluates to \c true.
-    If so, the stream arguments are processed and sent to the tracers
+    If so, the stream arguments are processed and sent to the \l QTracer objects
     registered with the category.
 
     \note Arguments are not processed if trace output for the category is not
@@ -390,7 +414,7 @@ void QLoggingCategory::setFilterRules(const QString &rules)
 
     \snippet qtracer/ftracer.cpp 6
 
-    \sa qCTraceGuard()
+    \sa qCTraceGuard() QTraceGuard
 */
 
 /*!
@@ -402,11 +426,12 @@ void QLoggingCategory::setFilterRules(const QString &rules)
     storage. The guard constructor checks whether
     \l QLoggingCategory::isTraceEnabled() evaluates to \c true.
     If so, the stream arguments are processed and the \c{start()}
-    functions of the tracers registered with the \a category are called.
+    functions of the \l QTracer objects registered with the \a category are
+    called.
 
     The guard destructor also checks whether the category is enabled for
     tracing and if so, the \c{end()}
-    functions of the tracers registered with the \a category are called.
+    functions of the \l QTracer objects registered with the \a category are called.
 
     \note Arguments are always processed, even if trace output for the
     category is disabled. They will, however, in that case not be passed
@@ -416,7 +441,7 @@ void QLoggingCategory::setFilterRules(const QString &rules)
 
     \snippet qtracer/ftracer.cpp 4
 
-    \sa qCTrace()
+    \sa qCTrace() QTracer
 */
 
 /*!