1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: Some cleanup of class documentation

Browse Source 
Change-Id: I62f89157e57189a97151f9661bc354af9bd67468
Reviewed-by: Kai Koehne <kai.koehne@qt.io>
This commit is contained in:
Kavindra Palaraja 2019-07-15 14:04:57 +02:00
parent f2f1a93c58
commit 46f3b40a6d
1 changed files with 125 additions and 138 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

253
src/corelib/io/qloggingcategory.cpp
View File

@ -70,14 +70,16 @@ static void setBoolLane(QBasicAtomicInt *atomic, bool enable, int shift)
QLoggingCategory represents a certain logging category - identified by a QLoggingCategory represents a certain logging category - identified by a
string - at runtime. A category can be configured to enable or disable string - at runtime. A category can be configured to enable or disable
logging of messages per message type. Whether a message type is enabled or logging of messages per message type.
not can be checked with the \l isDebugEnabled(), \l isInfoEnabled(),
\l isWarningEnabled(), and \l isCriticalEnabled() methods.
All objects are meant to be configured by a common registry (see also To check whether a message type is enabled or not, use one of these methods:
\l{Configuring Categories}). Different objects can also represent the same \l isDebugEnabled(), \l isInfoEnabled(), \l isWarningEnabled(), and
category. It is therefore not recommended to export objects across module \l isCriticalEnabled().
boundaries, nor to manipulate the objects directly, nor to inherit from
All objects are meant to be configured by a common registry, as described in
\l{Configuring Categories}. Different objects can also represent the same
category. Therefore, it's \b{not} recommended to export objects across
module boundaries, to manipulate the objects directly, or to inherit from
QLoggingCategory. QLoggingCategory.
\section1 Creating Category Objects \section1 Creating Category Objects
@ -87,17 +89,17 @@ static void setBoolLane(QBasicAtomicInt *atomic, bool enable, int shift)
\snippet qloggingcategory/main.cpp 1 \snippet qloggingcategory/main.cpp 1
\note Category names are free text. However, to allow easy configuration Category names are free text; to configure categories using \l{Logging Rules}, their
of the categories using \l{Logging Rules} the names should follow some rules: names should follow this convention:
\list \list
\li Use letters and numbers only. \li Use letters and numbers only.
\li Further structure categories into common areas by using dots. \li Use dots to further structure categories into common areas.
\li Avoid the category names \c{debug}, \c{info}, \c{warning}, and \c{critical}. \li Avoid the category names: \c{debug}, \c{info}, \c{warning}, and \c{critical}.
\li Category names starting with \c{qt} are reserved for Qt modules. \li Category names with the \c{qt} prefix are solely reserved for Qt modules.
\endlist \endlist
QLoggingCategory objects implicitly defined by Q_LOGGING_CATEGORY() QLoggingCategory objects that are implicitly defined by Q_LOGGING_CATEGORY()
are created on first use in a thread-safe manner. are created on first use, in a thread-safe manner.
\section1 Checking Category Configuration \section1 Checking Category Configuration
@ -105,8 +107,8 @@ static void setBoolLane(QBasicAtomicInt *atomic, bool enable, int shift)
\l isWarningEnabled(), \l isCriticalEnabled(), as well as \l isEnabled() \l isWarningEnabled(), \l isCriticalEnabled(), as well as \l isEnabled()
to check whether messages for the given message type should be logged. to check whether messages for the given message type should be logged.
\note The qCDebug(), qCWarning(), qCCritical() macros prevent arguments The qCDebug(), qCWarning(), and qCCritical() macros prevent arguments from
from being evaluated if the respective message types are not enabled for the being evaluated if the respective message types are not enabled for the
category, so explicit checking is not needed: category, so explicit checking is not needed:
\snippet qloggingcategory/main.cpp 4 \snippet qloggingcategory/main.cpp 4
@ -119,28 +121,27 @@ static void setBoolLane(QBasicAtomicInt *atomic, bool enable, int shift)
\snippet qloggingcategory/main.cpp 5 \snippet qloggingcategory/main.cpp 5
will log messages of type \c QtWarningMsg, \c QtCriticalMsg, \c QtFatalMsg, but will logs messages of type \c QtWarningMsg, \c QtCriticalMsg, \c QtFatalMsg, but
ignore messages of type \c QtDebugMsg and \c QtInfoMsg. ignores messages of type \c QtDebugMsg and \c QtInfoMsg.
If no argument is passed, all messages will be logged. If no argument is passed, all messages are logged.
\section1 Configuring Categories \section1 Configuring Categories
The default configuration of categories can be overridden either by setting logging You can override the default configuration for categories either by setting
rules, or by installing a custom filter. logging rules, or by installing a custom filter.
\section2 Logging Rules \section2 Logging Rules
Logging rules allow logging for categories to be enabled or disabled in a Logging rules let you enable or disable logging for categories in a flexible
flexible way. Rules are specified in text, where every line must have the way. Rules are specified in text, where every line must have the format:
format
\snippet code/src_corelib_io_qloggingcategory.cpp 0 \snippet code/src_corelib_io_qloggingcategory.cpp 0
\c <category> is the name of the category, potentially with \c{*} as a \c <category> is the name of the category, potentially with \c{*} as a
wildcard symbol as the first or last character (or at both positions). wildcard symbol for the first or last character; or at both positions.
The optional \c <type> must be either \c debug, \c info, \c warning, or \c critical. The optional \c <type> must be \c debug, \c info, \c warning, or \c critical.
Lines that do not fit this scheme are ignored. Lines that don't fit this scheme are ignored.
Rules are evaluated in text order, from first to last. That is, if two rules Rules are evaluated in text order, from first to last. That is, if two rules
apply to a category/type, the rule that comes later is applied. apply to a category/type, the rule that comes later is applied.
@ -149,27 +150,25 @@ static void setBoolLane(QBasicAtomicInt *atomic, bool enable, int shift)
\snippet code/src_corelib_io_qloggingcategory.cpp 1 \snippet code/src_corelib_io_qloggingcategory.cpp 1
Since Qt 5.3, logging rules are also Logging rules are automatically loaded from the \c [Rules] section in a logging
automatically loaded from the \c [Rules] section of a logging configuration file. These configuration files are looked up in the QtProject
configuration file. Such configuration files are looked up in the QtProject configuration directory, or explicitly set in a \c QT_LOGGING_CONF environment
configuration directory, or explicitly set in a \c QT_LOGGING_CONF variable:
environment variable:
\snippet code/src_corelib_io_qloggingcategory.cpp 2 \snippet code/src_corelib_io_qloggingcategory.cpp 2
Since Qt 5.3, logging rules can also be specified in a \c QT_LOGGING_RULES Logging rules can also be specified in a \c QT_LOGGING_RULES environment variable;
environment variable. And since Qt 5.6, multiple rules can also be multiple rules can also be separated by semicolons:
separated by semicolons:
\snippet code/src_corelib_io_qloggingcategory.cpp 3 \snippet code/src_corelib_io_qloggingcategory.cpp 3
Rules set by \l setFilterRules() take precedence over rules specified Rules set by \l setFilterRules() take precedence over rules specified in the
in the QtProject configuration directory, and can, in turn, be QtProject configuration directory. In turn, these rules can be overwritten by those
overwritten by rules from the configuration file specified by from the configuration file specified by \c QT_LOGGING_CONF, and those set by
\c QT_LOGGING_CONF, and rules set by \c QT_LOGGING_RULES. \c QT_LOGGING_RULES.
Order of evaluation: The order of evaluation is as follows:
\list \list 1
\li [QLibraryInfo::DataPath]/qtlogging.ini \li [QLibraryInfo::DataPath]/qtlogging.ini
\li QtProject/qtlogging.ini \li QtProject/qtlogging.ini
\li \l setFilterRules() \li \l setFilterRules()
@ -178,18 +177,10 @@ static void setBoolLane(QBasicAtomicInt *atomic, bool enable, int shift)
\endlist \endlist
The \c QtProject/qtlogging.ini file is looked up in all directories returned The \c QtProject/qtlogging.ini file is looked up in all directories returned
by QStandardPaths::GenericConfigLocation, e.g. by QStandardPaths::GenericConfigLocation.
\list Set the \c QT_LOGGING_DEBUG environment variable to find out where you logging
\li on \macos and iOS: \c ~/Library/Preferences rules are loaded from.
\li on Unix: \c ~/.config, \c /etc/xdg
\li on Windows: \c %LOCALAPPDATA%, \c %ProgramData%,
\l QCoreApplication::applicationDirPath(),
QCoreApplication::applicationDirPath() + \c "/data"
\endlist
Set the \c QT_LOGGING_DEBUG environment variable to see from where
logging rules are loaded.
\section2 Installing a Custom Filter \section2 Installing a Custom Filter
@ -211,7 +202,7 @@ static void setBoolLane(QBasicAtomicInt *atomic, bool enable, int shift)
If \a category is \c{0}, the category name is changed to \c "default". If \a category is \c{0}, the category name is changed to \c "default".
Note that \a category must be kept valid during the lifetime of this object. \note \a category must be kept valid during the lifetime of this object.
*/ */
QLoggingCategory::QLoggingCategory(const char *category) QLoggingCategory::QLoggingCategory(const char *category)
: d(0), : d(0),
@ -226,7 +217,7 @@ QLoggingCategory::QLoggingCategory(const char *category)
If \a category is \c{0}, the category name is changed to \c "default". If \a category is \c{0}, the category name is changed to \c "default".
Note that \a category must be kept valid during the lifetime of this object. \note \a category must be kept valid during the lifetime of this object.
\since 5.4 \since 5.4
*/ */
@ -251,7 +242,7 @@ void QLoggingCategory::init(const char *category, QtMsgType severityLevel)
} }
/*! /*!
Destructs a QLoggingCategory object. Destroys a QLoggingCategory object.
*/ */
QLoggingCategory::~QLoggingCategory() QLoggingCategory::~QLoggingCategory()
{ {
@ -268,24 +259,24 @@ QLoggingCategory::~QLoggingCategory()
/*! /*!
\fn bool QLoggingCategory::isDebugEnabled() const \fn bool QLoggingCategory::isDebugEnabled() const
Returns \c true if debug messages should be shown for this category. Returns \c true if debug messages should be shown for this category;
Returns \c false otherwise. \c false otherwise.
\note The \l qCDebug() macro already does this check before executing any \note The \l qCDebug() macro already does this check before running any
code. However, calling this method may be useful to avoid code. However, calling this method may be useful to avoid the
expensive generation of data that is only used for debug output. expensive generation of data for debug output only.
*/ */
/*! /*!
\fn bool QLoggingCategory::isInfoEnabled() const \fn bool QLoggingCategory::isInfoEnabled() const
Returns \c true if informational messages should be shown for this category. Returns \c true if informational messages should be shown for this category;
Returns \c false otherwise. \c false otherwise.
\note The \l qCInfo() macro already does this check before executing any \note The \l qCInfo() macro already does this check before executing any
code. However, calling this method may be useful to avoid code. However, calling this method may be useful to avoid the
expensive generation of data that is only used for debug output. expensive generation of data for debug output only.
\since 5.5 \since 5.5
*/ */
@ -294,28 +285,28 @@ QLoggingCategory::~QLoggingCategory()
/*! /*!
\fn bool QLoggingCategory::isWarningEnabled() const \fn bool QLoggingCategory::isWarningEnabled() const
Returns \c true if warning messages should be shown for this category. Returns \c true if warning messages should be shown for this category;
Returns \c false otherwise. \c false otherwise.
\note The \l qCWarning() macro already does this check before executing any \note The \l qCWarning() macro already does this check before executing any
code. However, calling this method may be useful to avoid code. However, calling this method may be useful to avoid the
expensive generation of data that is only used for debug output. expensive generation of data for debug output only.
*/ */
/*! /*!
\fn bool QLoggingCategory::isCriticalEnabled() const \fn bool QLoggingCategory::isCriticalEnabled() const
Returns \c true if critical messages should be shown for this category. Returns \c true if critical messages should be shown for this category;
Returns \c false otherwise. \c false otherwise.
\note The \l qCCritical() macro already does this check before executing any \note The \l qCCritical() macro already does this check before executing any
code. However, calling this method may be useful to avoid code. However, calling this method may be useful to avoid the
expensive generation of data that is only used for debug output. expensive generation of data for debug output only.
*/ */
/*! /*!
Returns \c true if a message of type \a msgtype for the category should be Returns \c true if a message of type \a msgtype for the category should be
shown. Returns \c false otherwise. shown; \c false otherwise.
*/ */
bool QLoggingCategory::isEnabled(QtMsgType msgtype) const bool QLoggingCategory::isEnabled(QtMsgType msgtype) const
{ {
@ -332,11 +323,11 @@ bool QLoggingCategory::isEnabled(QtMsgType msgtype) const
/*! /*!
Changes the message type \a type for the category to \a enable. Changes the message type \a type for the category to \a enable.
This method is meant to be used only from inside a filter This method is meant for use only from inside a filter installed with
installed by \l installFilter(). See \l {Configuring Categories} for \l installFilter(). For an overview on how to configure categories globally,
an overview on how to configure categories globally. see \l {Configuring Categories}.
\note \c QtFatalMsg cannot be changed. It will always remain \c true. \note \c QtFatalMsg cannot be changed; it will always remain \c true.
*/ */
void QLoggingCategory::setEnabled(QtMsgType type, bool enable) void QLoggingCategory::setEnabled(QtMsgType type, bool enable)
{ {
@ -359,28 +350,25 @@ void QLoggingCategory::setEnabled(QtMsgType type, bool enable)
/*! /*!
\fn QLoggingCategory &QLoggingCategory::operator()() \fn QLoggingCategory &QLoggingCategory::operator()()
Returns the object itself. This allows both a QLoggingCategory variable, and Returns the object itself. This allows for both: a QLoggingCategory variable, and
a factory method returning a QLoggingCategory, to be used in \l qCDebug(), a factory method that returns a QLoggingCategory, to be used in \l qCDebug(),
\l qCWarning(), \l qCCritical() macros. \l qCWarning(), or \l qCCritical() macros.
*/ */
/*! /*!
\fn const QLoggingCategory &QLoggingCategory::operator()() const \fn const QLoggingCategory &QLoggingCategory::operator()() const
Returns the object itself. This allows both a QLoggingCategory variable, and Returns the object itself. This allows for both: a QLoggingCategory variable, and
a factory method returning a QLoggingCategory, to be used in \l qCDebug(), a factory method that returns a QLoggingCategory, to be used in \l qCDebug(),
\l qCWarning(), \l qCCritical() macros. \l qCWarning(), or \l qCCritical() macros.
*/ */
/*! /*!
Returns a pointer to the global category \c "default" that Returns a pointer to the global category \c "default" that is used, for
is used e.g. by qDebug(), qInfo(), qWarning(), qCritical(), qFatal(). example, by qDebug(), qInfo(), qWarning(), qCritical(), or qFatal().
\note The returned pointer may be null during destruction of \note The pointer returned may be null during destruction of static objects.
static objects. Also, don't \c delete this pointer, as ownership of the category isn't transferred.
\note Ownership of the category is not transferred, do not
\c delete the returned pointer.
*/ */
QLoggingCategory *QLoggingCategory::defaultCategory() QLoggingCategory *QLoggingCategory::defaultCategory()
@ -391,8 +379,7 @@ QLoggingCategory *QLoggingCategory::defaultCategory()
/*! /*!
\typedef QLoggingCategory::CategoryFilter \typedef QLoggingCategory::CategoryFilter
This is a typedef for a pointer to a function with the following This is a typedef for a pointer to a function with the following signature:
signature:
\snippet qloggingcategory/main.cpp 20 \snippet qloggingcategory/main.cpp 20
@ -408,14 +395,13 @@ QLoggingCategory *QLoggingCategory::defaultCategory()
filter is free to change the respective category configuration with filter is free to change the respective category configuration with
\l setEnabled(). \l setEnabled().
The filter might be called from different threads, but never concurrently. When you define your filter, note that it can be called from different threads; but never
The filter shall not call any static functions of QLoggingCategory. concurrently. This filter cannot call any static functions from QLoggingCategory.
Example: Example:
\snippet qloggingcategory/main.cpp 21 \snippet qloggingcategory/main.cpp 21
An alternative way of configuring the default filter is via Alternatively, you can configure the default filter via \l setFilterRules().
\l setFilterRules().
*/ */
QLoggingCategory::CategoryFilter QLoggingCategory::CategoryFilter
QLoggingCategory::installFilter(QLoggingCategory::CategoryFilter filter) QLoggingCategory::installFilter(QLoggingCategory::CategoryFilter filter)
@ -425,15 +411,15 @@ QLoggingCategory::installFilter(QLoggingCategory::CategoryFilter filter)
/*! /*!
Configures which categories and message types should be enabled through a Configures which categories and message types should be enabled through a
a set of \a rules. set of \a rules.
Example: Example:
\snippet qloggingcategory/main.cpp 2 \snippet qloggingcategory/main.cpp 2
\note The rules might be ignored if a custom category filter is installed \note The rules might be ignored if a custom category filter is installed
with \l installFilter(), or if the user defined \c QT_LOGGING_CONF or \c QT_LOGGING_RULES with \l installFilter(), or if the user has defined the \c QT_LOGGING_CONF
environment variable. or the \c QT_LOGGING_RULES environment variable.
*/ */
void QLoggingCategory::setFilterRules(const QString &rules) void QLoggingCategory::setFilterRules(const QString &rules)
{ {
@ -446,7 +432,7 @@ void QLoggingCategory::setFilterRules(const QString &rules)
\threadsafe \threadsafe
\since 5.2 \since 5.2
Returns an output stream for debug messages in the logging category Returns an output stream for debug messages in the logging category,
\a category. \a category.
The macro expands to code that checks whether The macro expands to code that checks whether
@ -457,8 +443,8 @@ void QLoggingCategory::setFilterRules(const QString &rules)
\snippet qloggingcategory/main.cpp 10 \snippet qloggingcategory/main.cpp 10
\note Arguments are not processed if debug output for the category is not \note Arguments aren't processed if the debug output for that \a category is not
enabled, so do not rely on any side effects. enabled, so don't rely on any side effects.
\sa qDebug() \sa qDebug()
*/ */
@ -469,16 +455,16 @@ void QLoggingCategory::setFilterRules(const QString &rules)
\threadsafe \threadsafe
\since 5.3 \since 5.3
Logs a debug message \a message in the logging category \a category. Logs a debug message, \a message, in the logging category, \a category.
\a message might contain place holders that are replaced by additional \a message may contain place holders to be replaced by additional arguments,
arguments, similar to the C printf() function. similar to the C printf() function.
Example: Example:
\snippet qloggingcategory/main.cpp 13 \snippet qloggingcategory/main.cpp 13
\note Arguments might not be processed if debug output for the category is \note Arguments aren't processed if the debug output for that \a category is not
not enabled, so do not rely on any side effects. enabled, so don't rely on any side effects.
\sa qDebug() \sa qDebug()
*/ */
@ -489,7 +475,7 @@ void QLoggingCategory::setFilterRules(const QString &rules)
\threadsafe \threadsafe
\since 5.5 \since 5.5
Returns an output stream for informational messages in the logging category Returns an output stream for informational messages in the logging category,
\a category. \a category.
The macro expands to code that checks whether The macro expands to code that checks whether
@ -500,8 +486,8 @@ void QLoggingCategory::setFilterRules(const QString &rules)
\snippet qloggingcategory/main.cpp qcinfo_stream \snippet qloggingcategory/main.cpp qcinfo_stream
\note Arguments are not processed if debug output for the category is not \note If the debug output for a particular category isn't enabled, arguments
enabled, so do not rely on any side effects. won't be processed, so don't rely on any side effects.
\sa qInfo() \sa qInfo()
*/ */
@ -512,16 +498,16 @@ void QLoggingCategory::setFilterRules(const QString &rules)
\threadsafe \threadsafe
\since 5.5 \since 5.5
Logs an informational message \a message in the logging category \a category. Logs an informational message, \a message, in the logging category, \a category.
\a message might contain place holders that are replaced by additional \a message may contain place holders to be replaced by additional arguments,
arguments, similar to the C printf() function. similar to the C printf() function.
Example: Example:
\snippet qloggingcategory/main.cpp qcinfo_printf \snippet qloggingcategory/main.cpp qcinfo_printf
\note Arguments might not be processed if debug output for the category is \note If the debug output for a particular category isn't enabled, arguments
not enabled, so do not rely on any side effects. won't be processed, so don't rely on any side effects.
\sa qInfo() \sa qInfo()
*/ */
@ -532,7 +518,7 @@ void QLoggingCategory::setFilterRules(const QString &rules)
\threadsafe \threadsafe
\since 5.2 \since 5.2
Returns an output stream for warning messages in the logging category Returns an output stream for warning messages in the logging category,
\a category. \a category.
The macro expands to code that checks whether The macro expands to code that checks whether
@ -543,8 +529,8 @@ void QLoggingCategory::setFilterRules(const QString &rules)
\snippet qloggingcategory/main.cpp 11 \snippet qloggingcategory/main.cpp 11
\note Arguments are not processed if warning output for the category is not \note If the warning output for a particular category isn't enabled, arguments
enabled, so do not rely on any side effects. won't be processed, so don't rely on any side effects.
\sa qWarning() \sa qWarning()
*/ */
@ -555,16 +541,16 @@ void QLoggingCategory::setFilterRules(const QString &rules)
\threadsafe \threadsafe
\since 5.3 \since 5.3
Logs a warning message \a message in the logging category \a category. Logs a warning message, \a message, in the logging category, \a category.
\a message might contain place holders that are replaced by additional \a message may contain place holders to be replaced by additional arguments,
arguments, similar to the C printf() function. similar to the C printf() function.
Example: Example:
\snippet qloggingcategory/main.cpp 14 \snippet qloggingcategory/main.cpp 14
\note Arguments might not be processed if warning output for the category is \note If the warning output for a particular category isn't enabled, arguments
not enabled, so do not rely on any side effects. won't be processed, so don't rely on any side effects.
\sa qWarning() \sa qWarning()
*/ */
@ -575,7 +561,7 @@ void QLoggingCategory::setFilterRules(const QString &rules)
\threadsafe \threadsafe
\since 5.2 \since 5.2
Returns an output stream for critical messages in the logging category Returns an output stream for critical messages in the logging category,
\a category. \a category.
The macro expands to code that checks whether The macro expands to code that checks whether
@ -586,8 +572,9 @@ void QLoggingCategory::setFilterRules(const QString &rules)
\snippet qloggingcategory/main.cpp 12 \snippet qloggingcategory/main.cpp 12
\note Arguments are not processed if critical output for the category is not
enabled, so do not rely on any side effects. \note If the critical output for a particular category isn't enabled, arguments
won't be processed, so don't rely on any side effects.
\sa qCritical() \sa qCritical()
*/ */
@ -598,16 +585,16 @@ void QLoggingCategory::setFilterRules(const QString &rules)
\threadsafe \threadsafe
\since 5.3 \since 5.3
Logs a critical message \a message in the logging category \a category. Logs a critical message, \a message, in the logging category, \a category.
\a message might contain place holders that are replaced by additional \a message may contain place holders to be replaced by additional arguments,
arguments, similar to the C printf() function. similar to the C printf() function.
Example: Example:
\snippet qloggingcategory/main.cpp 15 \snippet qloggingcategory/main.cpp 15
\note Arguments might not be processed if critical output for the category \note If the critical output for a particular category isn't enabled, arguments
is not enabled, so do not rely on any side effects. won't be processed, so don't rely on any side effects.
\sa qCritical() \sa qCritical()
*/ */
@ -633,7 +620,7 @@ void QLoggingCategory::setFilterRules(const QString &rules)
\a string identifier. By default, all message types are enabled. \a string identifier. By default, all message types are enabled.
Only one translation unit in a library or executable can define a category Only one translation unit in a library or executable can define a category
with a specific name. The implicitly defined QLoggingCategory object is with a specific name. The implicitly-defined QLoggingCategory object is
created on first use, in a thread-safe manner. created on first use, in a thread-safe manner.
This macro must be used outside of a class or method. This macro must be used outside of a class or method.
@ -650,7 +637,7 @@ void QLoggingCategory::setFilterRules(const QString &rules)
and more severe are enabled, types with a lower severity are disabled. and more severe are enabled, types with a lower severity are disabled.
Only one translation unit in a library or executable can define a category Only one translation unit in a library or executable can define a category
with a specific name. The implicitly defined QLoggingCategory object is with a specific name. The implicitly-defined QLoggingCategory object is
created on first use, in a thread-safe manner. created on first use, in a thread-safe manner.
This macro must be used outside of a class or method. It is only defined This macro must be used outside of a class or method. It is only defined