Doc: Update debugger topics

- Add info about PDB
- Edit info about setting up debuggers and add (existing)
  screenshots
- Update info about Add Breakpoints view
- Move some text around

Task-number: QTCREATORBUG-28778
Change-Id: Ice3813ef2d4b143ed1f9d246aa6c029829dee60f
Reviewed-by: David Schulz <david.schulz@qt.io>
Reviewed-by: Christian Stenger <christian.stenger@qt.io>

1 files changed, 92 insertions, 86 deletions

diff --git a/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc b/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc
index 17d03346c3..961b2d2e74 100644
--- a/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc
+++ b/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc
@@ -35,7 +35,7 @@
             low level virtual machine (LLVM) project, LLDB.
         \li Debug QML and Java code and Qt Quick applications -
             QML/JavaScript debugger.
-        \li Debug Python source code - \c pdb.
+        \li Debug Python source code - PDB.
     \endlist
 
     The following sections describe how to set up, launch, and interact with the
@@ -130,44 +130,47 @@
     debugger, select the \inlineimage icons/qtcreator-debug-button.png
     (\uicontrol {Start Debugging of Startup Project}) button or press \key F5.
 
-    \QC checks whether the compiled program is up-to-date, and rebuilds and
+    \QC checks whether the compiled application is up-to-date, and rebuilds and
     deploys it if you set the \uicontrol {Build before deploying} field to
     build the whole project or the application to run and select he
     \uicontrol {Always deploy before running} check box in
     \uicontrol Edit > \uicontrol Preferences > \uicontrol {Build & Run} >
-    \uicontrol General. To debug the program without deploying
+    \uicontrol General. To debug the application without deploying
     it, select \uicontrol Debug > \uicontrol {Start Debugging} >
     \uicontrol {Start Debugging Without Deployment}.
 
-    The debugger then takes over and starts the program with suitable
+    The debugger then takes over and starts the application with suitable
     parameters.
 
     When using GDB or CDB as debug backend, you can specify additional commands
-    to execute before and after the backend and debugged program are started or
+    to execute before and after the backend and debugged application are started or
     attached in \uicontrol Edit > \uicontrol Preferences > \uicontrol Debugger >
     \uicontrol GDB and \uicontrol CDB. For more information, see
     \l{Debugger Preferences}.
 
-    To allow reading the user's default .gdbinit file on debugger startup,
+    To let the debugger read the user's default .gdbinit file when it starts,
     select the \uicontrol {Load .gdbinit file on startup} check box in
     GDB settings. For more information, see \l{Specifying GDB Settings}.
 
-    \note Starting a C++ program in the debugger can take a long time, typically
-    in the range of several seconds to minutes if complex features are used.
+    \note Starting a C++ application under the control of the debugger can take
+    a long time. Typically, in the range of several seconds to minutes if you use
+    complex features.
 
-    \section1 Launching the Debugger in Different Modes
+    For \l {Creating Widget-Based Qt for Python Applications}{Python} projects,
+    start debugging the \c main.py file. If you encounter problems, check the
+    active build target in the \l{Building for Multiple Platforms}{kit selector}.
+
+    \section1 Debugger Operating Modes
 
     The debugger plugin can run the native debuggers in various operating modes
-    depending on where and how the debugged process is started and run. Some of
+    depending on where and how you start and run the debugged process. Some of
     the modes are only available for a particular operating system or platform.
 
     In general, \key F5 and the \uicontrol {Start Debugging of Startup Project}
-    button are set up in a
-    way to start the operating mode that is commonly used in a given context. So
-    if the current project is set up as a C++ application using the \MinGW
-    toolchain targeting desktop Windows, the GDB engine will be started in Start
-    Internal mode. If the current project is a QML application using C++
-    plugins, a "mixed" QML/C++ engine will be started, with the C++ parts being
+    button start the operating mode that fits the context. So, for a C++
+    application that uses the \MinGW toolchain targeting desktop Windows, the GDB
+    engine starts in \e {start internal} mode. For a QML application that uses C++
+    plugins, a \e mixed QML/C++ engine starts, with the C++ parts being
     handled by GDB and GDB server remote debugging.
 
     Change the run configuration parameters (such as
@@ -179,24 +182,24 @@
 
     \list
 
-       \li \b{Start Internal} to debug applications developed inside \QC such as
-            a Qt based GUI application.
+       \li \e{Start internal} to debug applications developed inside \QC, such as
+            a Qt Widgets-based application.
 
-       \li \b{Start External} to start and debug processes without a proper \QC
+       \li \e{Start external} to start and debug processes without a proper \QC
             project setup, either locally or on a remote machine.
 
-       \li \b{Attach} to debug processes already started and running outside
+       \li \e{Attach} to debug processes already started and running outside
             \QC, either locally or on a remote machine.
 
-       \li \b{Core} to debug crashed processes on Unix.
+       \li \e{Core} to debug crashed processes on Unix.
 
-       \li \b{Post-mortem} to debug crashed processes on Windows.
+       \li \e{Post-mortem} to debug crashed processes on Windows.
 
     \endlist
 
-    \section2 Launching in Start Internal Mode
+    \section2 Start Internal
 
-    Start Internal mode is the default start mode for most projects, including
+    Start internal mode is the default start mode for most projects, including
     all projects using a desktop Qt version and plain C++ projects.
 
     If you need a console window to operate your application, for example
@@ -211,19 +214,19 @@
     override the console set in the Windows system environment variables.
     Note that the native console does not prompt on application exit.
 
-    To launch the debugger in Start Internal mode, click the
+    To launch the debugger in start internal mode, click the
     \uicontrol {Start Debugging} button for the active project.
 
     You can specify breakpoints before or after launching the debugger.
     For more information, see \l{Setting Breakpoints}.
 
-    \section2 Launching in Start External Mode
+    \section2 Start External
 
-    You can debug any executable already present on your local or on a remote
+    You can debug any executable on your local or on a remote
     machine without using a project. You specify a build and run kit that
     identifies the device to debug the application on.
 
-    While this mode does not strictly require a project to be opened in \QC,
+    While this mode does not strictly require a project to be open in \QC,
     opening it makes setting breakpoints and stepping through the code easier.
 
     To start and debug an external application:
@@ -261,7 +264,7 @@
             configuration to use.
     \endlist
 
-    \section2 Launching in Attach Mode
+    \section2 Attach
 
     You can attach the debugger to applications that are already running or
     instruct the debugger to attach to an application when it starts.
@@ -285,7 +288,7 @@
 
     To terminate the selected process, select \uicontrol {Kill Process}.
 
-    While this mode does not strictly require a project to be opened in \QC,
+    While this mode does not strictly require a project to be open in \QC,
     opening it makes setting breakpoints and stepping through the code easier.
 
     You can specify breakpoints before or after attaching the debugger to the
@@ -312,14 +315,14 @@
             process to start.
     \endlist
 
-    \section2 Launching in Core Mode
+    \section2 Core
 
-    The Core mode is used to inspect \e {core} files (crash dumps) that are
+    Use the core mode to inspect \e {core} files (crash dumps) that are
     generated from crashed processes on Linux and Unix systems if the system is
     set up to allow this.
 
     To enable the dumping of core files on a Unix system, enter the following
-    command in the shell from which the application will be launched:
+    command in the shell from which the application is launched:
 
     \code
     ulimit -c unlimited
@@ -350,12 +353,12 @@
             the \c sysroot to use instead of the default \c sysroot.
     \endlist
 
-    Also in this mode, using a properly configured project that has the
-    sources of the crashed program is not strictly necessary, but helpful.
+    Even though using a properly configured project that has the sources of the
+    crashed application is not strictly necessary, it is helpful.
 
-    \section2 Launching in Post-Mortem Mode
+    \section2 Post-Mortem
 
-    The post-mortem mode is available only on Windows, if you have installed the
+    The post-mortem mode is available only on Windows, if you installed the
     debugging tools for Windows.
 
     The \QC installation program asks you whether you want to register \QC as a
@@ -365,7 +368,7 @@
 
     You can launch the debugger in the post-mortem mode if an application
     crashes on Windows. Click the \uicontrol {Debug in \QC} button in the error
-    message that is displayed by the Windows operating system.
+    message from the Windows operating system.
 */
 
 /*!
@@ -552,43 +555,35 @@
     \title Debug Mode Views
 
     In the \uicontrol Debug mode, you can inspect the state of your
-    application while debugging. You can interact with the debugger
-    in many ways, including the following:
+    application while debugging.
 
-    \list
+    \image qtcreator-debugger-views.webp {Debug mode views while debugging}
+
+    You can interact with the debugger in many ways:
 
-        \li Go through a program line-by-line or instruction-by-instruction.
+    \list
 
-        \li Interrupt running programs.
+        \li Interrupt running applications.
 
         \li Set breakpoints.
 
+        \li Step through an application line-by-line or
+            instruction-by-instruction.
+
         \li Examine the contents of the call stack.
 
         \li Examine and modify contents of local and global variables.
 
         \li Examine and modify registers and memory contents of
-            the debugged program.
+            the debugged application.
 
         \li Examine the list of loaded shared libraries.
 
         \li Disassemble sections of code.
     \endlist
 
-    \QC displays the raw information from the native debuggers in a clear
-    and concise manner with the goal to simplify the debugging process as much
-    as possible without losing the power of the native debuggers.
-
-    In addition to the generic IDE functionality of the stack view, views
-    for locals and expressions, registers, and so on, \QC includes features to
-    make debugging Qt-based applications easy. The debugger plugin understands
-    the internal layout of several Qt classes, for example, QString, the Qt
-    containers, and most importantly QObject (and classes derived from it), as
-    well as most containers of the C++ Standard Library and some GCC extensions.
-    It uses this deeper understanding to present objects of such classes in a
-    useful way.
-
-    Interact with the program you are debugging in the following views.
+    The following table summarizes the \uicontrol Debug mode views with links to
+    more information.
 
     \table
     \header
@@ -597,12 +592,14 @@
         \li Learn More
     \row
         \li Stack
-        \li Examine the the nested function calls leading to the current position
+        \li Examine the nested function calls leading to the current position
             as a call stack trace.
         \li \l {Viewing Call Stack Trace}
     \row
-        \li Breakpoints
-        \li Set \e {breakpoints} with conditions make the application stop in
+        \li Breakpoint Preset
+
+            Breakpoints
+        \li Set \e {breakpoints} with conditions to make the application stop in
             a controlled way. A \e {watchpoint} stops the application when the
             value of an expression changes.
         \li \l {Setting Breakpoints}
@@ -658,17 +655,17 @@
 
     \section1 Managing Debug Views
 
-    The availability of views depends on whether
-    you are debugging C++ or QML. Frequently used views are shown by
-    default and rarely used ones are hidden. To change the default settings,
-    select \uicontrol View > \uicontrol Views, and then select views to
-    display or hide. Alternatively, you can enable or disable views from the
-    context menu of the title bar of any visible debug mode view.
+    When you are not debugging, the \uicontrol Debug mode shows the
+    \uicontrol {Debugger Preset} perspective:
+
+    \image qtcreator-debugger-views-initial.webp {Initial Debug mode views}
 
-    \image qtcreator-debugger-views.png {Debug mode views}
+    During debugging, the mode shows the views that you usually need to
+    debug C++ or QML applications. To show other views or to hide views,
+    select \uicontrol Views.
 
-    You can drag and drop the views in \QC to new positions on the screen. The
-    size and position of views are saved for future sessions. Select
+    You can drag the views in \QC to new positions on the screen. \QC saves the
+    size and position of views as a perspective for future sessions. Select
     \uicontrol View > \uicontrol Views > \uicontrol {Reset to Default Layout}
     to reset the views to their original sizes and positions.
 
@@ -680,13 +677,18 @@
 
     \section1 Customizing Debug Views
 
-    You can change the appearance and behavior of the debug views by specifying
-    settings in \uicontrol Preferences > \uicontrol Debugger. For example, you can:
+    To change the appearance and behavior of the debug views, set preferences
+    in \uicontrol Edit > \uicontrol Preferences > \uicontrol Debugger >
+    \uicontrol General.
+
+    \image qtcreator-debugger-general-options.png {General tab in Debugger preferences}
+
+    For example, you can:
 
     \list
         \li Use alternating row colors in debug views.
         \li Adopt font size changes from the main editor.
-        \li Have tooltips displayed in the main editor while you are debugging.
+        \li Show tooltips in the main editor while you are debugging.
         \li Close temporary source and memory views and switch to the previously
             used \QC mode when the debugger exits.
         \li Bring \QC to the foreground when the debugged application is
@@ -703,17 +705,19 @@
 
     \title Stopping Applications
 
-    Once the program starts running under the control of the debugger, it
-    behaves and performs as usual. You can interrupt a running C++ program by
-    selecting \uicontrol Debug > \uicontrol Interrupt. The program is
-    automatically interrupted when a breakpoint is hit.
+    Once the application starts running under the control of the debugger, it
+    behaves and performs as usual.
+
+    To interrupt a running C++ application, select \uicontrol Debug >
+    \uicontrol Interrupt. The debugger automatically interrupts
+    the application when it hits a \l {Setting Breakpoints}{breakpoint}.
 
-    Once the program stops, \QC:
+    Once the application stops, \QC:
 
     \list
 
         \li Retrieves data representing the \l{Viewing Call Stack Trace}
-            {call stack} at the program's current position.
+            {call stack} at the application's current position.
 
         \li Retrieves the contents of \l{Local Variables and Function Parameters}
             {local variables}.
@@ -725,6 +729,8 @@
             {Disassembler} views if you are debugging C++ based applications.
 
     \endlist
+    You can \l{Examining Data}{Examine} and change variables, set or remove
+    breakpoints, and then continue running the application.
 */
 
 /*!
@@ -753,7 +759,7 @@
        \li To leave the current function or subfunction, press \key {Shift+F11}
            (\key {Command+Shift+T} on \macos).
 
-       \li To continue running the program, press \key F5.
+       \li To continue running the application, press \key F5.
 
        \li To run to the line that has the cursor, press \key {Ctrl+F10}
            (\key {Shift+F8} on \macos).
@@ -763,7 +769,7 @@
 
     \endlist
 
-    You can continue executing the program until the current
+    You can continue executing the application until the current
     function completes or jump to an arbitrary position in the current function.
 
     \section1 Stepping Into Code
@@ -849,15 +855,15 @@
     \omit
     \section2 Creating Snapshots
 
-    A snapshot has the complete state of the debugged program at a time,
+    A snapshot has the complete state of the debugged application at a time,
     including the full memory contents.
 
-    To create snapshots of a debugged program, select \uicontrol {Create Snapshot}
+    To create snapshots of a debugged application, select \uicontrol {Create Snapshot}
     in the context menu in the \uicontrol {Debugger Perspectives} view.
 
     Double-click on entries in the \uicontrol {Debugger Perspectives} view to
     switch between snapshots. The debug mode views are updated to reflect the state
-    of the program at time of taking the snapshot.
+    of the application at time of taking the snapshot.
 
     \note Creating snapshots involves creating core files of the debugged process,
     requiring significant amount of disk space. For details, see
@@ -873,7 +879,7 @@
 
     \title Viewing Threads
 
-    If a multi-threaded program is interrupted, the \uicontrol Threads view or
+    If a multi-threaded application is interrupted, the \uicontrol Threads view or
     the combobox named \uicontrol Threads in the debugger status bar can be used
     to switch from one thread to another. The \uicontrol Stack view adjusts
     itself accordingly.
@@ -956,7 +962,7 @@
     values of registers that recently have changed are highlighted in red and empty
     register values as well as leading zeroes are grayed out.
 
-    In addition it is possible to edit the content of registers while the program is
+    In addition it is possible to edit the content of registers while the application is
     stopped. This applies to both General-purpose and Special-purpose registers.
     Registers can be edited in the standard condensed view or in their particular parts
     if the register is displayed expanded.