Doc: Improve the structure and readability

Change-Id: I9f945291e849c3298583ecf893c8429feb9f2051
Reviewed-by: Simon Hausmann <simon.hausmann@qt.io>
Reviewed-by: Ulf Hermann <ulf.hermann@qt.io>

1 files changed, 145 insertions, 125 deletions

diff --git a/doc/src/qmlapp/debugging.qdoc b/doc/src/qmlapp/debugging.qdoc
index 78ca1027..a5b36fa3 100644
--- a/doc/src/qmlapp/debugging.qdoc
+++ b/doc/src/qmlapp/debugging.qdoc
@@ -29,107 +29,126 @@
 \page qtquick-debugging.html
 \ingroup qtquick-tools
 \title Debugging QML Applications
-\brief debugging tools in QML
+\brief Provides information on how to use QML's debugging tools.
 
-\section1 Console API
-
-\section2 Log
-\keyword console log
-
-\c console.log, console.debug, console.info, console.warn and console.error can be used to print
-debugging information to the console. For example:
-
-\code
-function f(a, b) {
-  console.log("a is ", a, "b is ", b);
-}
-\endcode
-
-The output is generated using the qCDebug, qCWarning, qCCritical methods in C++,
-with a category of "qml" or "js", depending on the type of file doing the logging.
-See also \l {Debugging Techniques}.
-
-\section2 Assert
-\keyword console assert
-
-\c console.assert tests that an expression is true. If not, it will write an optional message
-to the console and print the stack trace.
-
-\code
-function f() {
-  var x = 12
-  console.assert(x == 12, "This will pass");
-  console.assert(x > 12, "This will fail");
-}
-\endcode
-
-\section2 Timer
-\keyword console time
-\keyword console timeEnd
-\c console.time and console.timeEnd log the time (in milliseconds) that was spent between
-the calls. Both take a string argument that identifies the measurement. For example:
-
-\code
-function f() {
-    console.time("wholeFunction");
-    console.time("firstPart");
-    // first part
-    console.timeEnd("firstPart");
-    // second part
-    console.timeEnd("wholeFunction");
-}
-\endcode
+When you develop an application with QML, there are many ways to debug possible issues that you
+may face. The sections below describe the debugging tools available and how to use them.
 
-\section2 Trace
-\keyword console trace
-
-\c console.trace prints the stack trace of the JavaScript execution at the point where
-it was called. The stack trace info contains the function name, file name, line number
-and column number. The stack trace is limited to last 10 stack frames.
-
-\section2 Count
-\keyword console count
-\c console.count prints the current number of times a particular piece of code has been executed,
-along with a message. That is,
-
-\code
-function f() {
-  console.count("f called");
-}
-\endcode
-
-will print \c{f called: 1}, \c{f called: 2} ... whenever \c{f()} is executed.
-
-\section2 Profile
-\keyword console profile
-\c console.profile turns on the QML and JavaScript profilers. Nested calls are not
-supported and a warning will be printed to the console.
-
-\keyword console profileEnd
-\c console.profileEnd turns off the QML and JavaScript profilers. Calling this function
-without a previous call to console.profile will print a warning to the console. A
-profiling client should have been attached before this call to receive and store the
-profiling data. For example:
-
-\code
-function f() {
-    console.profile();
-    //Call some function that needs to be profiled.
-    //Ensure that a client is attached before ending
-    //the profiling session.
-    console.profileEnd();
-}
-\endcode
+\section1 Console API
 
-\section2 Exception
-\keyword console exception
-\c console.exception prints an error message together with the stack trace of JavaScript
-execution at the point where it is called.
+\table
+    \header
+        \li Feature
+        \li Description
+    \row
+        \keyword console log
+        \li Log
+        \li Use \c{console.log}, \c{console.debug}, \c{console.info}, \c{console.warn}, or
+            \c{console.error} to print debugging information to the console.
+
+            For example:
+
+            \code
+            function f(a, b) {
+              console.log("a is ", a, "b is ", b);
+            }
+            \endcode
+
+            The output is generated using the qCDebug, qCWarning, or qCCritical methods in C++,
+            with a category of \c qml or \c js, depending on the type of file doing the logging.
+            See also \l {Debugging Techniques}.
+    \row
+        \keyword console assert
+        \li Assert
+        \li \c console.assert tests that an expression is true. If not, it writes an optional
+            message to the console and prints the stack trace.
+
+            For example:
+
+            \code
+            function f() {
+              var x = 12
+              console.assert(x == 12, "This will pass");
+              console.assert(x > 12, "This will fail");
+            }
+            \endcode
+    \row
+        \keyword console time
+        \keyword console timeEnd
+        \li Timer
+        \li \c{console.time} and \c{console.timeEnd} log the time (in milliseconds) that was spent
+            between the calls. Both take a string argument that identifies the measurement.
+
+            For example:
+
+            \code
+            function f() {
+                console.time("wholeFunction");
+                console.time("firstPart");
+                // first part
+                console.timeEnd("firstPart");
+                // second part
+                console.timeEnd("wholeFunction");
+            }
+            \endcode
+    \row
+        \keyword console trace
+        \li Trace
+        \li \c console.trace prints the stack trace of the JavaScript execution at the point where
+            it was called. This stack trace information contains the function name, file name,
+            line number, and column number. The stack trace is limited to last 10 stack frames.
+    \row
+        \keyword console count
+        \li Count
+        \li \c console.count prints the current number of times a particular piece of code has run,
+            along with a message.
+
+            For example:
+
+            \code
+            function f() {
+              console.count("f called");
+            }
+            \endcode
+
+            The code sample above prints \c{f called: 1}, \c{f called: 2} ... whenever \c{f()} is
+            run.
+    \row
+        \keyword console profile
+        \li Profile
+        \li \c console.profile turns on the QML and JavaScript profilers. Nested calls are not
+            supported and prints a warning to the console.
+    \row
+        \keyword console profileEnd
+        \li ProfileEnd
+        \li \c console.profileEnd turns off the QML and JavaScript profilers. Calling this function
+            without a previous call to \c console.profile prints a warning to the console. A
+            profiling client needs to be attached before this call to receive and store the
+            profiling data.
+
+            For example:
+
+            \code
+            function f() {
+                console.profile();
+                //Call some function that needs to be profiled.
+                //Ensure that a client is attached before ending
+                //the profiling session.
+                console.profileEnd();
+            }
+            \endcode
+
+    \row
+        \keyword console exception
+        \li Exception
+        \li \c console.exception prints an error message together with the stack trace of
+            JavaScript execution at the point where it is called.
+\endtable
 
 \section1 Debugging Module Imports
 
-The \c QML_IMPORT_TRACE environment variable can be set to enable debug output
-from QML's import loading mechanisms.
+Set the \c QML_IMPORT_TRACE environment variable to enable debug output from QML's import loading
+mechanisms.
 
 For example, for a simple QML file like this:
 
@@ -139,8 +158,8 @@ import QtQuick 2.3
 Rectangle { width: 100; height: 100 }
 \endqml
 
-If you set \c {QML_IMPORT_TRACE=1} before running the \l{qtquick-qmlscene.html}
-{QML Scene} (or your QML C++ application), you will see output similar to this:
+If you set \c {QML_IMPORT_TRACE=1} before running the \l{qtquick-qmlscene.html}{QML Scene} or your
+QML C++ application, you will see output similar to:
 
 \code
 QQmlImportDatabase::addImportPath "/qt-sdk/imports"
@@ -153,67 +172,68 @@ QQmlImportDatabase::resolveType "Rectangle" = "QDeclarativeRectangle"
 \section1 QML Debugging Infrastructure
 \keyword declarative_debug
 \keyword qml debug
-The \l{Qt QML} module provides services for debugging, inspecting, and profiling
-applications via a TCP port.
+
+The \l{Qt QML} module provides services for debugging, inspecting, and profiling applications via a
+TCP port.
 
 \section2 Enabling the Infrastructure
 
-You have to explicitly enable the debugging infrastructure when compiling your
-application. If you use qmake, you can add the configuration parameters to
-the project .pro file:
+When you compile your application, you must explicitly enable the debugging infrastructure. If you
+use qmake, you can add the configuration parameters to the project \c{.pro} file:
 
 \list
     \li Qt Quick 1: \c {CONFIG+=declarative_debug}
     \li Qt Quick 2: \c {CONFIG+=qml_debug}
 \endlist
 
-If you use some other build system, you can pass the following defines to the
-compiler:
+If you use another build system, you can pass the following defines to the compiler:
 
 \list
     \li Qt Quick 1: \c {QT_DECLARATIVE_DEBUG}
     \li Qt Quick 2: \c {QT_QML_DEBUG}
 \endlist
 
-\note Enabling the debugging infrastructure might compromise the integrity of
-the application and system, and therefore, you should only enable it in a
-controlled environment. When the infrastructure is enabled, the application
-displays the following warning:
+\note Enabling the debugging infrastructure may compromise the integrity of your application and
+system, and therefore, you should only enable it in a controlled environment. When the
+infrastructure is enabled, the application displays the following warning:
 
 \c {QML debugging is enabled. Only use this in a safe environment.}
 
 \section2 Starting Applications
 
-Start the application with the following arguments:
+To enable debugging from the start, start the application with the following arguments:
 
 \c {-qmljsdebugger=port:<port_from>[,port_to][,host:<ip address>][,block]}
 
-Where \c {port_from} (mandatory) specifies either the debugging port or the
-start port of a range of ports when \c {port_to} is specified, \c {ip address}
-(optional) specifies the IP address of the host where the application is
-running, and \c block (optional) prevents the application from running until the
-debug client connects to the server. This enables debugging from the start.
+Where:
+\list
+    \li the mandatory \c {port_from} specifies either the debugging port or the start port of a
+        range of ports when \c {port_to} is specified
+    \li the optional \c {ip address} specifies the IP address of the host where the application is
+        running
+    \li the optional \c block prevents the application from running until the debug client connects
+        to the server
+\endlist
 
-After the application has successfully started, it displays the following
-message:
+After the application has successfully started, it displays the following message:
 
 \c {QML Debugger: Waiting for connection on port <port_number>}
 
 \section2 Connecting to Applications
 
-When the application is running, an IDE or a tool that implements the binary
-protocol can connect to the open port.
+When the application is running, an IDE or a tool that implements the binary protocol can connect
+to the open port.
 
-Qt provides a \c qmlprofiler command line tool to capture profiling data in a
-file. To run the tool, enter the following command:
+Qt provides a \c qmlprofiler command line tool to capture profiling data in a file. To run this
+tool, enter the following command:
 
 \c {qmlprofiler -p <port> -attach <ip address>}
 
 \section1 Debugging with Qt Creator
 
-Qt Creator uses the debugging infrastructure to debug, inspect
-and profile Qt Quick applications on the desktop as well as on remote devices.
-Qt Creator provides integrated clients for debugging JS, inspecting the object
-tree, and profiling the activities of a QML engine. For more information, see
-\l{Qt Creator: Debugging Qt Quick Projects}.
+Qt Creator uses the debugging infrastructure to debug, inspect, and profile Qt Quick applications
+on the desktop as well as on remote devices. Qt Creator provides integrated clients for debugging
+JavaScript, inspecting the object tree, and profiling the activities of a QML engine. For more
+information, see \l{Qt Creator: Debugging Qt Quick Projects}.
+
 */