[prev in list] [next in list] [prev in thread] [next in thread]
List: kde-commits
Subject: [gluon] core: core: Improve documentation of Log class
From: Arjen Hiemstra <ahiemstra () heimr ! nl>
Date: 2014-08-31 22:01:21
Message-ID: E1XODBZ-0003xU-4Y () scm ! kde ! org
[Download RAW message or body]
Git commit 6579468d77d368baf624dac1377da61288c9b485 by Arjen Hiemstra.
Committed on 31/08/2014 at 21:55.
Pushed by ahiemstra into branch 'master'.
core: Improve documentation of Log class
M +41 -0 core/log.h
http://commits.kde.org/gluon/6579468d77d368baf624dac1377da61288c9b485
diff --git a/core/log.h b/core/log.h
index af91599..1181fdb 100644
--- a/core/log.h
+++ b/core/log.h
@@ -45,6 +45,8 @@ namespace GluonCore
=
/**
* The category a message belongs to.
+ *
+ * \todo It probably makes sense to change category to a QByteArray so=
we have more flexibility.
*/
enum LogCategory
{
@@ -74,6 +76,9 @@ namespace GluonCore
=
/**
* Helper class for building a log message to output.
+ *
+ * While it is possible to construct this manually, we recommend using=
the LOG()
+ * and related macros instead, as they greatly simplify the process.
*/
class GLUONCORE_EXPORT LogBuilder
{
@@ -97,6 +102,40 @@ namespace GluonCore
* to log and where to log to. LogBuilder constructs a LogData object =
that is sent
* to Log on destruction. Log then outputs the data of that LogData ob=
ject to
* whatever output was selected.
+ *
+ * There is no way to use the Log class to directly send a message. In=
stead, create
+ * an instance of LogBuilder to add a message. LogBuilder will send th=
e message on
+ * destruction, so it is best to create it on the stack.
+ *
+ * ## LogLevel and LogCategory
+ *
+ * Each message has a level and category. These are used to determine =
whether a
+ * message should be logged at all. During compile time, a maximum log=
level can
+ * be set using the `GLUON_MAX_LOG_LEVEL` define. This will define a g=
lobal maximum
+ * logging level, anything above that level will be ignored.The value =
of this define
+ * defaults to LogDebug for debug builds and LogWarning for release bu=
ilds.
+ *
+ * In addition, each category can have a different maximum logging lev=
el set at runtime.
+ * If a message is under the maximum log level but over a category's r=
untime defined
+ * maximum log level it is also ignored. Finally, if it passes the che=
ck the category
+ * and log level will be used to print a log message.
+ *
+ * ## Logging Context
+ *
+ * Each message additionally has a context. This is a string used to p=
rovide
+ * context to a message, that is, indicate where the message originate=
d from. The Log
+ * class maintains a stack of contexts. Each time setCurrentContext is=
called, this
+ * will add a new context to the stack, whereas clearCurrentContext wi=
ll remove the top
+ * context from the stack. The macros DEBUG(), NOTICE(), INFO(), WARNI=
NG(), ERROR() and
+ * CRITICAL() will all provide a default context of file, line and fun=
ction name. The
+ * macros suffixed with _NC will provide an empty context, which means=
it will use
+ * whatever context is current. This can be used to provide a differen=
t context for
+ * messages not originating from a certain file, like compilation erro=
rs from a script
+ * file pointing to the script file rather than the C++ source file.
+ *
+ * \warning Code supplied to the LOG() related macros may be ignored o=
r even completely
+ * removed depending on the maximum compile and runtime log level. The=
refore, you should
+ * never rely on logging code to perform important function like initi=
alization.
*/
class GLUONCORE_EXPORT Log : public Singleton< Log >
{
@@ -215,6 +254,8 @@ namespace GluonCore
=
/**
* A series of macros to output at a certain log level, using the default =
category and an empty context.
+ *
+ * Use these in combination with Log::setCurrentContext() to provide custo=
m contexts, like Asset files.
*/
#define CRITICAL_NC() LOG( GLUON_DEFAULT_LOG_CATEGORY, GluonCore::LogCriti=
cal, QByteArray() )
#define ERROR_NC() LOG( GLUON_DEFAULT_LOG_CATEGORY, GluonCore::LogError, Q=
ByteArray() )
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic