From f62927868491b7ed7e7dbb76fa87883502799759 Mon Sep 17 00:00:00 2001
From: hjk <hjk@qt.io>
Date: Wed, 14 Aug 2019 15:31:17 +0200
Subject: [PATCH] Doc: Describe unclaimed and claimed breakpoints

Change-Id: I56bca8fe51cc4de63ce2f0ac195c9014c8b6c5b9
Reviewed-by: hjk <hjk@qt.io>
---
 .../qtcreator-debugger-breakpoint-preset.png  | Bin 0 -> 3383 bytes
 .../qtcreator-unclaimed-breakpoint-icon.png   | Bin 0 -> 160 bytes
 .../debugger/creator-debugger-common.qdocinc  | 129 +++++++++++-------
 3 files changed, 80 insertions(+), 49 deletions(-)
 create mode 100644 doc/images/qtcreator-debugger-breakpoint-preset.png
 create mode 100644 doc/images/qtcreator-unclaimed-breakpoint-icon.png

diff --git a/doc/images/qtcreator-debugger-breakpoint-preset.png b/doc/images/qtcreator-debugger-breakpoint-preset.png
new file mode 100644
index 0000000000000000000000000000000000000000..e5fa486f2e2cfcfda47ca9c6ccbd88ffa7f749da
GIT binary patch
literal 3383
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

literal 0
HcmV?d00001

diff --git a/doc/images/qtcreator-unclaimed-breakpoint-icon.png b/doc/images/qtcreator-unclaimed-breakpoint-icon.png
new file mode 100644
index 0000000000000000000000000000000000000000..2db094be14bde8a7a354b987647eb6c15a730cd8
GIT binary patch
literal 160
zcmeAS@N?(olHy`uVBq!ia0y~yU=UznU=ZYBU|?YQc%)c@fq^02)5S4FB0Tv=Kbyn`
zt~q{&4-7mkd4zw=Ie3VH&2YXV6DN;>0HavM*#?Hyj!cXmOpFSQk}8anC5!?N8H|w(
zO3xN^A6WZ${RjCD2R`pcE*S$88-~JP|2Sm%<_hfKN~t$|Alfj4g~5rp_wWbqat)Bx
Mp00i_>zopr07P;t#{d8T

literal 0
HcmV?d00001

diff --git a/doc/src/debugger/creator-debugger-common.qdocinc b/doc/src/debugger/creator-debugger-common.qdocinc
index 5ebb66ab154..5437b0d2a55 100644
--- a/doc/src/debugger/creator-debugger-common.qdocinc
+++ b/doc/src/debugger/creator-debugger-common.qdocinc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2018 The Qt Company Ltd.
+** Copyright (C) 2019 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -29,16 +29,7 @@
 
     \section1 Setting Breakpoints
 
-    A breakpoint represents a position or sets of positions in the code that,
-    when executed, interrupts the program being debugged and passes the control
-    to you. You can then examine the state of the interrupted program, or
-    continue execution either line-by-line or continuously.
 
-    \QC shows breakpoints in the \uicontrol Breakpoints view which is enabled
-    by default. The \uicontrol Breakpoints view is also accessible when the
-    debugger and the program being debugged is not running.
-
-    \image qtcreator-debug-breakpoints.png "Breakpoints view"
 
     You can associate breakpoints with:
 
@@ -68,9 +59,48 @@
     The interruption of a program by a breakpoint can be restricted with certain
     conditions.
 
-    You can set and delete breakpoints before the program starts running or
-    while it is running under the debugger's control. Breakpoints are saved
-    together with a session.
+    Breakpoints come in two varieties: \c unclaimed and \c claimed.
+    An unclaimed breakpoint represents a task to interrupt the debugged
+    program and passes the control to you later. I has two states:
+    \c pending and \c implanted.
+
+    Unclaimed breakpoints are stored as a part of a session and exist
+    independently of whether a program is being debugged or not. They
+    are listed in the \uicontrol {Breakpoint Preset} view and in the
+    editor using the \inlineimage qtcreator-unclaimed-breakpoint-icon.png
+    (\uicontrol {Unclaimed Breakpoint}) icon, when they refer to a position
+    in code.
+
+    \image qtcreator-debugger-breakpoint-preset.png "Breakpoint Preset" view
+
+    When a debugger starts, the debugging backend identifies breakpoints
+    from the set of unclaimed breakpoints that might be handled by the
+    debugged program and claims them for its own exclusive use. Claimed
+    breakpoints are listed in the \uicontrol {Breakpoints} view of the
+    running debugger. This view only exists while the debugger is running.
+
+    When a debugger claims a breakpoint, the unclaimed breakpoint disappears
+    from the \uicontrol {Breakpoint Preset} view, to appear as a pending
+    breakpoint in the \uicontrol Breakpoints view.
+
+    At various times, attempts are made to implant pending breakpoints into
+    the debugged process. Succesfull implantation might create one or more
+    implanted breakpoints, each associated with an actual address in
+    the debugged breakpoint. The implantation might also move a breakpoint
+    marker in the editor from an empty line to the next line for which the
+    actual code was generated, for example. Implanted breakpoint icons don't
+    have the hourglass overlay.
+
+    When the debugger ends, its claimed breakpoints, both pending and
+    implanted, will return to the unclaimed state and re-appear in the
+    \uicontrol{Breakpoint Preset} view.
+
+    When an implanted breakpoint is hit during the execution of the
+    debugged program, control is passed back to you.
+    You can then examine the state of the interrupted program, or
+    continue execution either line-by-line or continuously.
+
+    \image qtcreator-debug-breakpoints.png "Breakpoints view"
 
     \section2 Adding Breakpoints
 
@@ -86,12 +116,14 @@
                     (\key F8 for \macos) at a particular line you want the
                     program to stop.
 
-                \li In the \uicontrol Breakpoints view, double-click in the empty
-                    part of the view.
-
-                \li In the \uicontrol Breakpoints view, select
-                    \uicontrol {Add Breakpoint} in the context menu.
+                \li In the \uicontrol {Breakpoint Preset} view or the
+                    \uicontrol Breakpoints view:
 
+                    \list
+                        \li Double-click the empty part of the view.
+                        \li Right-click the view, and select
+                            \uicontrol {Add Breakpoint} in the context menu.
+                    \endlist
             \endlist
 
         \li In the \uicontrol {Breakpoint type} field, select the location in the
@@ -119,7 +151,16 @@
 
     \section2 Moving Breakpoints
 
-    To move the breakpoint, drag and drop a breakpoint marker to another line.
+    To move a breakpoint:
+
+    \list
+        \li Drag and drop a breakpoint marker to another line
+            in the text editor.
+        \li In the \uicontrol {Breakpoint Preset} view or the
+             \uicontrol Breakpoints view, select
+             \uicontrol {Edit Selected Breakpoints}, and set the
+             line number in the \uicontrol {Line number} field.
+    \endlist
 
     \section2 Deleting Breakpoints
 
@@ -129,11 +170,15 @@
 
         \li Click the breakpoint marker in the text editor.
 
-        \li Select the breakpoint in the \uicontrol Breakpoints view and press
-            \key Delete.
-
-        \li Select \uicontrol {Delete Breakpoint} in the context menu in the
-            \uicontrol Breakpoints view.
+        \li In the \uicontrol {Breakpoint Preset} view or the
+            \uicontrol Breakpoints view:
+            \list
+                \li Select the breakpoint and press \key Delete.
+                \li Select \uicontrol {Delete Selected Breakpoints},
+                    \uicontrol {Delete Selected Breakpoints}, or
+                    \uicontrol {Delete Breakpoints of File} in the
+                    context menu.
+            \endlist
 
     \endlist
 
@@ -147,31 +192,17 @@
         \li Right-click the breakpoint marker in the text editor and select
             \uicontrol{Disable Breakpoint}.
 
-        \li Select the breakpoint in the \uicontrol Breakpoints view and press
-            \key Space.
-
-        \li Select \uicontrol {Disabled Breakpoint} in the context menu in the
-            \uicontrol Breakpoints view.
-
+        \li In the \uicontrol {Breakpoint Preset} view or the
+            \uicontrol Breakpoints view:
+            \list
+                \li Select the breakpoint and press \key Space.
+                \li Select \uicontrol {Disable Breakpoint} in the context menu.
+            \endlist
     \endlist
 
-    A disabled breakpoint is marked with a hollow read circle in the
-    text editor and the \uicontrol Breakpoint view.
-
-    To re-enable a temporarily disabled breakpoint:
-
-    \list
-
-        \li Right-click the marker of a disabled breakpoint in the text editor and
-            select \uicontrol{Enable Breakpoint}.
-
-        \li Select a disabled breakpoint in the \uicontrol Breakpoints view and press
-            \key Space.
-
-        \li Select \uicontrol {Disabled Breakpoint} in the context menu in the
-            \uicontrol Breakpoints view.
-
-    \endlist
+    A hollow breakpoint icon in the text editor and the views indicates a
+    disabled breakpoint. To re-enable a breakpoint, use any of the above
+    methods.
 
     With the notable exception of data breakpoints, breakpoints retain their
     enabled or disabled state when the debugged program is restarted.
@@ -185,8 +216,8 @@
 
     \list 1
 
-        \li Right-click in the \uicontrol Breakpoints view to open the context
-            menu, and select \uicontrol {Add Breakpoint}.
+        \li In the \uicontrol {Breakpoint Preset} or \uicontrol Breakpoints
+            view, select \uicontrol {Add Breakpoint} in the context menu.
 
         \li In the \uicontrol {Breakpoint type} field, select
             \uicontrol {Break on data access at fixed address}.