Logging: Mention 'best practices' for using QLoggingCategory

QLoggingCategory objects are meant to be mere 'handles' for the
registry. It's therefore not recommended to
- manipulate them directly (via setEnabled()), except in a filter
- export them across module boundaries
- subclass them

Subclassing QLoggingCategory also breaks compilations in a certain
circumstances (no variadic macros).

Task-number: QTBUG-37283
Change-Id: Ib12fb43d955902c7fa4583296d64afc5eca01200
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
This commit is contained in:
Kai Koehne 2014-04-23 10:32:07 +02:00 committed by The Qt Project
parent 27ea8fa99f
commit ee85cdee67

View File

@ -62,6 +62,12 @@ Q_GLOBAL_STATIC_WITH_ARGS(QLoggingCategory, qtDefaultCategory,
by a string - at runtime. Whether a category should be actually logged or
not can be checked with the \l isEnabled() methods.
All objects are meant to be configured by a common registry (see also
\l{Configuring Categories}). Different objects can also represent the same
category. It's therefore not recommended to export objects across module
boundaries, nor to manipulate the objects directly, nor to inherit from
QLoggingCategory.
\section1 Creating category objects
The Q_LOGGING_CATEGORY() and the Q_DECLARE_LOGGING_CATEGORY() macros