Link up the information about categorized logging better

The use of logging categories in console.log was far too obscure
relative to its usefulness. Most reusable QML components and most
applications could make good use of it, routinely.

Likewise Debugging Techniques didn't mention categorized logging, only
the older macros.

Debugging Techniques now links to Debugging QML Applications and
vice-versa, and both of them link to the LoggingCategory QML object.

It's good to have more info in QT_MESSAGE_PATTERN. Since we stopped
pasting qFunc() all over, it's good to have %{function} (even though it
goes missing in release builds); and I think %{time process} is a great
way to see message timing.  %{type} and %{appname} make the output too
long for my taste, but my usual %if syntax for the type is too verbose
to put here; and %{appname} was already here for some reason.

Link to QQuickItem::dumpItemTree() alongside the paragraph about
QObject::dumpObjectTree() and friends.

Change-Id: If1d1168ee85a82eb63a533da016c47f032f385c2
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
(cherry picked from commit 468529bed05abb595ae82e9b15707867b825d9eb)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

2 files changed, 32 insertions, 13 deletions

diff --git a/doc/src/development/debug.qdoc b/doc/src/development/debug.qdoc
index 32d09b541..ad26997a3 100644
--- a/doc/src/development/debug.qdoc
+++ b/doc/src/development/debug.qdoc
@@ -123,18 +123,29 @@
 
     \section1 Warning and Debugging Messages
 
-    Qt includes global macros for writing out warning and debug
-    text. You can use them for the following purposes:
+    Qt includes global C++ macros for writing out warning and debug text.
+    The plain macros use a default \l {QLoggingCategory}{logging category};
+    the categorized logging macros allow you to specify the category.
+    You can use them for the following purposes:
 
-    \list
-    \li qDebug() is used for writing custom debug output.
-    \li qInfo() is used for informational messages.
-    \li qWarning() is used to report warnings and recoverable errors in
-       your application.
-    \li qCritical() is used for writing critical error messages and
-       reporting system errors.
-    \li qFatal() is used for writing fatal error messages shortly before exiting.
-    \endlist
+    \table
+    \header \li Plain macro \li Categorized macro \li Purpose
+    \row \li qDebug()
+         \li qCDebug()
+         \li Used for writing custom debug output
+    \row \li qInfo()
+         \li qCInfo()
+         \li Used for informational messages
+    \row \li qWarning()
+         \li qCWarning()
+         \li Used to report warnings and recoverable errors in your application or library
+    \row \li qCritical()
+         \li qCCritical()
+         \li Used for writing critical error messages and reporting system errors
+    \row \li qFatal()
+         \li -
+         \li Used for writing messages about fatal errors shortly before exiting
+    \endtable
 
     If you include the <QtDebug> header file, the \c qDebug() macro
     can also be used as an output stream. For example:
@@ -150,7 +161,7 @@
     by setting the \c QT_MESSAGE_PATTERN environment variable. For example:
 
     \code
-    QT_MESSAGE_PATTERN="[%{type}] %{appname} (%{file}:%{line}) - %{message}"
+    QT_MESSAGE_PATTERN="[%{time process} %{type}] %{appname} %{category} %{function} - %{message}"
     \endcode
 
     The format is documented in qSetMessagePattern(). You can also install your
@@ -169,6 +180,8 @@
     looks or acts strangely. More useful if you use \l{QObject::setObjectName()}{object names}
     than not, but often useful even without names.
 
+    In QML, \l {QtQuick::Item::}{dumpItemTree()} serves the same purpose.
+
     \section1 Providing Support for the qDebug() Stream Operator
 
     You can implement the stream operator used by qDebug() to provide
@@ -224,6 +237,9 @@
     therefore recommend that you use a debug version of Qt when
     developing Qt-based software.
 
+    Logging and \l {LoggingCategory}{categorized logging} are also
+    possible in \l {Debugging QML Applications}{QML}.
+
     \section1 Common Bugs
 
     There is one bug that is so common that it deserves mention here:
diff --git a/doc/src/qmlapp/debugging.qdoc b/doc/src/qmlapp/debugging.qdoc
index 5b748b435..b0aa19526 100644
--- a/doc/src/qmlapp/debugging.qdoc
+++ b/doc/src/qmlapp/debugging.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2022 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -145,6 +145,9 @@ may face. The sections below describe the debugging tools available and how to u
             JavaScript execution at the point where it is called.
 \endtable
 
+Alternatively, a \l {QLoggingCategory}{logging category} can be passed as the
+first argument to any of these \c {console} functions. See \l [QML] LoggingCategory for more details.
+
 \section1 Debugging Module Imports
 
 Set the \c QML_IMPORT_TRACE environment variable to enable debug output from QML's import loading