From f733a0044ef9e31af0577d5b2695c659e29dc2e8 Mon Sep 17 00:00:00 2001 From: Kai Koehne Date: Mon, 2 Apr 2012 12:17:28 +0200 Subject: Logging: Make sure documentation shows up Move the documentation for qDebug, qWarning, qCritical, qFatal, QMessageHandler, QtMsgHandler, qtInstallMsgHandler, qInstallMessageHandler from qlogging.cpp to qglobal.cpp. For some reason it's not picked up from qlogging.cpp otherwise. Also, tweak the output so that e.g. qDebug and friends are correctly listed as macros. Change-Id: I8cabf04bae0e8ae9a31a40ebe2d3272c3a33653b Reviewed-by: Casper van Donderen --- src/corelib/global/qglobal.cpp | 199 ++++++++++++++++++++++++++++++++++++++++ src/corelib/global/qlogging.cpp | 195 --------------------------------------- 2 files changed, 199 insertions(+), 195 deletions(-) (limited to 'src') diff --git a/src/corelib/global/qglobal.cpp b/src/corelib/global/qglobal.cpp index f89b0b3421..8125161897 100644 --- a/src/corelib/global/qglobal.cpp +++ b/src/corelib/global/qglobal.cpp @@ -2886,4 +2886,203 @@ bool QInternal::activateCallbacks(Callback cb, void **parameters) otherwise. */ +/*! + \macro qDebug(const char *message, ...) + \relates + + Calls the message handler with the debug message \a message. If no + message handler has been installed, the message is printed to + stderr. Under Windows, the message is sent to the console, if it is a + console application; otherwise, it is sent to the debugger. This + function does nothing if \c QT_NO_DEBUG_OUTPUT was defined + during compilation. + + + If you pass the function a format string and a list of arguments, + it works in similar way to the C printf() function. The format + should be a Latin-1 string. + + Example: + + \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 24 + + If you include \c , a more convenient syntax is also + available: + + \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 25 + + With this syntax, the function returns a QDebug object that is + configured to use the QtDebugMsg message type. It automatically + puts a single space between each item, and outputs a newline at + the end. It supports many C++ and Qt types. + + To suppress the output at run-time, install your own message handler + with qInstallMessageHandler(). + + \sa qWarning(), qCritical(), qFatal(), qInstallMessageHandler(), + {Debugging Techniques} +*/ + +/*! + \macro qWarning(const char *message, ...) + \relates + + Calls the message handler with the warning message \a message. If no + message handler has been installed, the message is printed to + stderr. Under Windows, the message is sent to the debugger. This + function does nothing if \c QT_NO_WARNING_OUTPUT was defined + during compilation; it exits if the environment variable \c + QT_FATAL_WARNINGS is defined. + + This function takes a format string and a list of arguments, + similar to the C printf() function. The format should be a Latin-1 + string. + + Example: + \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 26 + + If you include , a more convenient syntax is + also available: + + \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 27 + + This syntax inserts a space between each item, and + appends a newline at the end. + + To suppress the output at runtime, install your own message handler + with qInstallMessageHandler(). + + \sa qDebug(), qCritical(), qFatal(), qInstallMessageHandler(), + {Debugging Techniques} +*/ + +/*! + \macro qCritical(const char *message, ...) + \relates + + Calls the message handler with the critical message \a message. If no + message handler has been installed, the message is printed to + stderr. Under Windows, the message is sent to the debugger. + + This function takes a format string and a list of arguments, + similar to the C printf() function. The format should be a Latin-1 + string. + + Example: + \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 28 + + If you include , a more convenient syntax is + also available: + + \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 29 + + A space is inserted between the items, and a newline is + appended at the end. + + To suppress the output at runtime, install your own message handler + with qInstallMessageHandler(). + + \sa qDebug(), qWarning(), qFatal(), qInstallMessageHandler(), + {Debugging Techniques} +*/ + +/*! + \macro qFatal(const char *message, ...) + \relates + + Calls the message handler with the fatal message \a message. If no + message handler has been installed, the message is printed to + stderr. Under Windows, the message is sent to the debugger. + + If you are using the \b{default message handler} this function will + abort on Unix systems to create a core dump. On Windows, for debug builds, + this function will report a _CRT_ERROR enabling you to connect a debugger + to the application. + + This function takes a format string and a list of arguments, + similar to the C printf() function. + + Example: + \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 30 + + To suppress the output at runtime, install your own message handler + with qInstallMessageHandler(). + + \sa qDebug(), qCritical(), qWarning(), qInstallMessageHandler(), + {Debugging Techniques} +*/ + +/*! + \typedef QtMsgHandler + \relates + \deprecated + + This is a typedef for a pointer to a function with the following + signature: + + \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 7 + + This typedef is deprecated, you should use QMessageHandler instead. + \sa QtMsgType, QMessageHandler, qInstallMsgHandler(), qInstallMessageHandler() +*/ + +/*! + \typedef QMessageHandler + \relates + \since 5.0 + + This is a typedef for a pointer to a function with the following + signature: + + \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 49 + + \sa QtMsgType, qInstallMessageHandler() +*/ + +/*! + \fn QMessageHandler qInstallMessageHandler(QMessageHandler handler) + \relates + \since 5.0 + + Installs a Qt message \a handler which has been defined + previously. Returns a pointer to the previous message handler + (which may be 0). + + The message handler is a function that prints out debug messages, + warnings, critical and fatal error messages. The Qt library (debug + mode) contains hundreds of warning messages that are printed + when internal errors (usually invalid function arguments) + occur. Qt built in release mode also contains such warnings unless + QT_NO_WARNING_OUTPUT and/or QT_NO_DEBUG_OUTPUT have been set during + compilation. If you implement your own message handler, you get total + control of these messages. + + The default message handler prints the message to the standard + output under X11 or to the debugger under Windows. If it is a + fatal message, the application aborts immediately. + + Only one message handler can be defined, since this is usually + done on an application-wide basis to control debug output. + + To restore the message handler, call \c qInstallMessageHandler(0). + + Example: + + \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 23 + + \sa QMessageHandler, QtMsgType, qDebug(), qWarning(), qCritical(), qFatal(), + {Debugging Techniques} +*/ + +/*! + \fn QtMsgHandler qInstallMsgHandler(QtMsgHandler handler) + \relates + \deprecated + + Installs a Qt message \a handler which has been defined + previously. This method is deprecated, use qInstallMessageHandler + instead. + \sa QtMsgHandler, qInstallMessageHandler +*/ + QT_END_NAMESPACE diff --git a/src/corelib/global/qlogging.cpp b/src/corelib/global/qlogging.cpp index b7eab7fffe..fe19ae631e 100644 --- a/src/corelib/global/qlogging.cpp +++ b/src/corelib/global/qlogging.cpp @@ -132,41 +132,6 @@ static void qt_message(QtMsgType msgType, const QMessageLogContext &context, con } #undef qDebug -/*! - \fn qDebug(const char *message, ...) - \relates - - Calls the message handler with the debug message \a msg. If no - message handler has been installed, the message is printed to - stderr. Under Windows, the message is sent to the console, if it is a - console application; otherwise, it is sent to the debugger. This - function does nothing if \c QT_NO_DEBUG_OUTPUT was defined - during compilation. - - If you pass the function a format string and a list of arguments, - it works in similar way to the C printf() function. The format - should be a Latin-1 string. - - Example: - - \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 24 - - If you include \c , a more convenient syntax is also - available: - - \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 25 - - With this syntax, the function returns a QDebug object that is - configured to use the QtDebugMsg message type. It automatically - puts a single space between each item, and outputs a newline at - the end. It supports many C++ and Qt types. - - To suppress the output at run-time, install your own message handler - with qInstallMessageHandler(). - - \sa qWarning(), qCritical(), qFatal(), qInstallMessageHandler(), - {Debugging Techniques} -*/ void QMessageLogger::debug(const char *msg, ...) { @@ -196,39 +161,6 @@ QNoDebug QMessageLogger::noDebug() #endif #undef qWarning -/*! - \fn qWarning(const char *message, ...) - \relates - - Calls the message handler with the warning message \a msg. If no - message handler has been installed, the message is printed to - stderr. Under Windows, the message is sent to the debugger. This - function does nothing if \c QT_NO_WARNING_OUTPUT was defined - during compilation; it exits if the environment variable \c - QT_FATAL_WARNINGS is defined. - - This function takes a format string and a list of arguments, - similar to the C printf() function. The format should be a Latin-1 - string. - - Example: - \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 26 - - If you include , a more convenient syntax is - also available: - - \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 27 - - This syntax inserts a space between each item, and - appends a newline at the end. - - To suppress the output at runtime, install your own message handler - with qInstallMessageHandler(). - - \sa qDebug(), qCritical(), qFatal(), qInstallMessageHandler(), - {Debugging Techniques} -*/ - void QMessageLogger::warning(const char *msg, ...) { va_list ap; @@ -250,35 +182,6 @@ QDebug QMessageLogger::warning() #endif #undef qCritical -/*! - \fn qCritical(const char *message, ...) - \relates - - Calls the message handler with the critical message \a msg. If no - message handler has been installed, the message is printed to - stderr. Under Windows, the message is sent to the debugger. - - This function takes a format string and a list of arguments, - similar to the C printf() function. The format should be a Latin-1 - string. - - Example: - \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 28 - - If you include , a more convenient syntax is - also available: - - \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 29 - - A space is inserted between the items, and a newline is - appended at the end. - - To suppress the output at runtime, install your own message handler - with qInstallMessageHandler(). - - \sa qDebug(), qWarning(), qFatal(), qInstallMessageHandler(), - {Debugging Techniques} -*/ void QMessageLogger::critical(const char *msg, ...) { @@ -301,31 +204,6 @@ QDebug QMessageLogger::critical() #endif #undef qFatal -/*! - \fn qFatal(const char *message, ...) - \relates - - Calls the message handler with the fatal message \a msg. If no - message handler has been installed, the message is printed to - stderr. Under Windows, the message is sent to the debugger. - - If you are using the \b{default message handler} this function will - abort on Unix systems to create a core dump. On Windows, for debug builds, - this function will report a _CRT_ERROR enabling you to connect a debugger - to the application. - - This function takes a format string and a list of arguments, - similar to the C printf() function. - - Example: - \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 30 - - To suppress the output at runtime, install your own message handler - with qInstallMessageHandler(). - - \sa qDebug(), qCritical(), qWarning(), qInstallMessageHandler(), - {Debugging Techniques} -*/ void QMessageLogger::fatal(const char *msg, ...) { @@ -775,68 +653,6 @@ extern Q_CORE_EXPORT void qWinMessageHandler(QtMsgType t, const QMessageLogConte const char *str); #endif -/*! - \typedef QtMsgHandler - \relates - \deprecated - - This is a typedef for a pointer to a function with the following - signature: - - \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 7 - - This typedef is deprecated, you should use QMessageHandler instead. - \sa QtMsgType, QMessageHandler, qInstallMsgHandler(), qInstallMessageHandler() -*/ - -/*! - \typedef QMessageHandler - \relates - \since 5.0 - - This is a typedef for a pointer to a function with the following - signature: - - \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 49 - - \sa QtMsgType, qInstallMessageHandler() -*/ - -/*! - \fn QMessageHandler qInstallMessageHandler(QMessageHandler handler) - \relates - \since 5.0 - - Installs a Qt message \a handler which has been defined - previously. Returns a pointer to the previous message handler - (which may be 0). - - The message handler is a function that prints out debug messages, - warnings, critical and fatal error messages. The Qt library (debug - mode) contains hundreds of warning messages that are printed - when internal errors (usually invalid function arguments) - occur. Qt built in release mode also contains such warnings unless - QT_NO_WARNING_OUTPUT and/or QT_NO_DEBUG_OUTPUT have been set during - compilation. If you implement your own message handler, you get total - control of these messages. - - The default message handler prints the message to the standard - output under X11 or to the debugger under Windows. If it is a - fatal message, the application aborts immediately. - - Only one message handler can be defined, since this is usually - done on an application-wide basis to control debug output. - - To restore the message handler, call \c qInstallMessageHandler(0). - - Example: - - \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 23 - - \sa qDebug(), qWarning(), qCritical(), qFatal(), QtMsgType, - {Debugging Techniques} -*/ - QMessageHandler qInstallMessageHandler(QMessageHandler h) { if (!messageHandler) @@ -850,17 +666,6 @@ QMessageHandler qInstallMessageHandler(QMessageHandler h) return old; } -/*! - \fn QtMsgHandler qInstallMsgHandler(QtMsgHandler handler) - \relates - \deprecated - - Installs a Qt message \a handler which has been defined - previously. This method is deprecated, use qInstallMessageHandler - instead. - \sa QtMsgHandler, qInstallMessageHandler -*/ - QtMsgHandler qInstallMsgHandler(QtMsgHandler h) { //if handler is 0, set it to the -- cgit v1.2.3