Fix doc and example of QLoggingCategory::installCategory()

Snippet [22] was unused and the example using snippet [21] neglected
to show how its oldCategoryFilter got initialized, which is what [22]
does. But it turns out the example code was crashy in any case, as it
left the oldCategoryFilter uninitialized (albeit probably null) until
the call to installFilter() had returned, and installFilter() calls
the new filter, so the new filter needs to check oldCategoryFilter
before calling it. The doc also failed to explain why it's OK to not
defer to the prior filter in these calls during installFilter(), so
revise the doc and example so that the latter behaves sensibly and
readers of the former are likely to use the function safely.

This amends commit 8f0654ceb878b6c8a08c7f5b790027c26e007c13 which
added the snippets and the use of one of them, but not the other.

Fixes: QTBUG-49704
Pick-to: 6.4 6.3 6.2 5.15
Change-Id: Iddb8d97b0bef417d8f16e7910730cfa59ea3e715
Reviewed-by: Kai Koehne <kai.koehne@qt.io>

1 files changed, 25 insertions, 7 deletions

diff --git a/src/corelib/io/qloggingcategory.cpp b/src/corelib/io/qloggingcategory.cpp
index 1a84f6359c..08b7b2d584 100644
--- a/src/corelib/io/qloggingcategory.cpp
+++ b/src/corelib/io/qloggingcategory.cpp
@@ -343,13 +343,27 @@ QLoggingCategory *QLoggingCategory::defaultCategory()
 */
 
 /*!
-    Installs a function \a filter that is used to determine which categories
-    and message types should be enabled. Returns a pointer to the previous
-    installed filter.
-
-    Every QLoggingCategory object created is passed to the filter, and the
-    filter is free to change the respective category configuration with
-    \l setEnabled().
+    \brief Take control of how logging categories are configured.
+
+    Installs a function \a filter that is used to determine which categories and
+    message types should be enabled. If \a filter is \nullptr, the default
+    message filter is reinstated. Returns a pointer to the previously-installed
+    filter.
+
+    Every QLoggingCategory object that already exists is passed to the filter
+    before \c installFilter() returns, and the filter is free to change each
+    category's configuration with \l setEnabled(). Any category it doesn't
+    change will retain the configuration it was given by the prior filter, so
+    the new filter does not need to delegate to the prior filter during this
+    initial pass over existing categories.
+
+    Any new categories added later will be passed to the new filter; a filter
+    that only aims to tweak the configuration of a select few categories, rather
+    than completely overriding the logging policy, can first pass the new
+    category to the prior filter, to give it its standard configuration, and
+    then tweak that as desired, if it is one of the categories of specific
+    interest to the filter. The code that installs the new filter can record the
+    return from \c installFilter() for the filter to use in such later calls.
 
     When you define your filter, note that it can be called from different threads; but never
     concurrently. This filter cannot call any static functions from QLoggingCategory.
@@ -357,6 +371,10 @@ QLoggingCategory *QLoggingCategory::defaultCategory()
     Example:
     \snippet qloggingcategory/main.cpp 21
 
+    installed (in \c{main()}, for example) by
+
+    \snippet qloggingcategory/main.cpp 22
+
     Alternatively, you can configure the default filter via \l setFilterRules().
  */
 QLoggingCategory::CategoryFilter