Updated Debug Tools (markdown)

Debug-Tools.md

@@ -1,42 +1,26 @@
 (work in progress) Also see [[Tips]].
 
 ## Index
-- [Debug Configuration Flags](#debug-configuration-flags)
+- [Item Picker](#item-picker)
 - [Metrics/Debugger window](#metricsdebugger-window)
 - [Debug Log](#debug-log)
+- [Debug Configuration Flags](#debug-configuration-flags)
 - [Debug Break Buttons](#debug-break-buttons)
 - [ID Stack Tool](#id-stack-tool)
-- [Item Picker](#item-picker)
 - [UTF-8 Encoding Viewer](utf-8-encoding-viewer)
 
 ----
 
-## Debug Configuration Flags
+## Item Picker
 
-![image](https://github.com/ocornut/imgui/assets/8225057/2b94e38b-e5ca-45ce-a562-ce6612c82535)
+https://github.com/ocornut/imgui/issues/2673
 
-Runtime flags available in `ImGuiIO` (and exposed in Demo->Configuration):
+The Item Picker will allow you to pick an item with the mouse and have Dear ImGui break within the call-stack of that item. This is useful if you have large UI / codebase and you would to easily find out where some UI item is emitted. 
-```cpp
+You can find it in _Metrics>Tools>Item Picker_ or expose it in your own UI by calling `ImGui::DebugStartItemPicker()`.See [#2673](https://github.com/ocornut/imgui/issues/2673) for more details.
-// Option to enable various debug tools showing buttons that will call the IM_DEBUG_BREAK() macro.
-// - The Item Picker tool will be available regardless of this being enabled, in order to maximize its discoverability.
-// - Requires a debugger being attached, otherwise IM_DEBUG_BREAK() options will appear to crash your application.
-//   e.g. io.ConfigDebugIsDebuggerPresent = ::IsDebuggerPresent() on Win32, or refer to ImOsIsDebuggerPresent() imgui_test_engine/imgui_te_utils.cpp for a Unix compatible version).
-bool ConfigDebugIsDebuggerPresent;   // = false          // Enable various tools calling IM_DEBUG_BREAK().
 
-// Tools to test correct Begin/End and BeginChild/EndChild behaviors.
+![image](https://github.com/ocornut/imgui/assets/8225057/52707662-37c3-4526-a82a-1f2f1daf25dd)
-// Presently Begin()/End() and BeginChild()/EndChild() needs to ALWAYS be called in tandem, regardless of return value of BeginXXX()
-// This is inconsistent with other BeginXXX functions and create confusion for many users.
-// We expect to update the API eventually. In the meanwhile we provide tools to facilitate checking user-code behavior.
-bool ConfigDebugBeginReturnValueOnce; // First-time calls to Begin()/BeginChild() will return false. NEEDS TO BE SET AT APPLICATION BOOT TIME if you don't want to miss windows.
-bool ConfigDebugBeginReturnValueLoop; // Some calls to Begin()/BeginChild() will return false. Will cycle through window depths then repeat. Suggested use: add "io.ConfigDebugBeginReturnValue = io.KeyShift" in your main loop then occasionally press SHIFT. Windows should be flickering while running.
 
-// Option to deactivate io.AddFocusEvent(false) handling. May facilitate interactions with a debugger when focus loss leads to clearing inputs data.
+![image](https://github.com/ocornut/imgui/assets/8225057/96828020-215c-4e30-879e-919fb8ea55f3)
-// Backends may have other side-effects on focus loss, so this will reduce side-effects but not necessary remove all of them.
-bool ConfigDebugIgnoreFocusLoss;      // Ignore io.AddFocusEvent(false), consequently not calling io.ClearInputKeys() in input processing.
-
-// Options to audit .ini data
-bool ConfigDebugIniSettings;          // Save .ini data with extra comments (particularly helpful for Docking, but makes saving slower)
-```
 
 ## Metrics/Debugger window
 
@@ -76,6 +60,33 @@ If `io.ConfigDebugIsDebuggerPresent` is enabled, an additional tooltip will appe
 
 ![image](https://github.com/ocornut/imgui/assets/8225057/a8f992a7-71dc-48c4-82da-6594ee08d65a)
 
+## Debug Configuration Flags
+
+![image](https://github.com/ocornut/imgui/assets/8225057/2b94e38b-e5ca-45ce-a562-ce6612c82535)
+
+Runtime flags available in `ImGuiIO` (and exposed in Demo->Configuration):
+```cpp
+// Option to enable various debug tools showing buttons that will call the IM_DEBUG_BREAK() macro.
+// - The Item Picker tool will be available regardless of this being enabled, in order to maximize its discoverability.
+// - Requires a debugger being attached, otherwise IM_DEBUG_BREAK() options will appear to crash your application.
+//   e.g. io.ConfigDebugIsDebuggerPresent = ::IsDebuggerPresent() on Win32, or refer to ImOsIsDebuggerPresent() imgui_test_engine/imgui_te_utils.cpp for a Unix compatible version).
+bool ConfigDebugIsDebuggerPresent;   // = false          // Enable various tools calling IM_DEBUG_BREAK().
+
+// Tools to test correct Begin/End and BeginChild/EndChild behaviors.
+// Presently Begin()/End() and BeginChild()/EndChild() needs to ALWAYS be called in tandem, regardless of return value of BeginXXX()
+// This is inconsistent with other BeginXXX functions and create confusion for many users.
+// We expect to update the API eventually. In the meanwhile we provide tools to facilitate checking user-code behavior.
+bool ConfigDebugBeginReturnValueOnce; // First-time calls to Begin()/BeginChild() will return false. NEEDS TO BE SET AT APPLICATION BOOT TIME if you don't want to miss windows.
+bool ConfigDebugBeginReturnValueLoop; // Some calls to Begin()/BeginChild() will return false. Will cycle through window depths then repeat. Suggested use: add "io.ConfigDebugBeginReturnValue = io.KeyShift" in your main loop then occasionally press SHIFT. Windows should be flickering while running.
+
+// Option to deactivate io.AddFocusEvent(false) handling. May facilitate interactions with a debugger when focus loss leads to clearing inputs data.
+// Backends may have other side-effects on focus loss, so this will reduce side-effects but not necessary remove all of them.
+bool ConfigDebugIgnoreFocusLoss;      // Ignore io.AddFocusEvent(false), consequently not calling io.ClearInputKeys() in input processing.
+
+// Options to audit .ini data
+bool ConfigDebugIniSettings;          // Save .ini data with extra comments (particularly helpful for Docking, but makes saving slower)
+```
+
 ## Debug Break Buttons
 
 When `io.ConfigDebugIsDebuggerPresent` is enabled, various `**DebugBreak**` buttons will appears in debug tools. Clicking them will attempt to break you in debugger in the desired location:
@@ -100,17 +111,6 @@ ImGui::ShowIdStackToolWindow();
 
 ![stack_tool_03](https://user-images.githubusercontent.com/8225057/136235657-a0ea5665-dcd1-423f-9be6-dc3f8ced8f12.png)
 
-## Item Picker
-
-https://github.com/ocornut/imgui/issues/2673
-
-The Item Picker will allow you to pick an item with the mouse and have Dear ImGui break within the call-stack of that item. This is useful if you have large UI / codebase and you would to easily find out where some UI item is emitted. 
-You can find it in _Metrics>Tools>Item Picker_ or expose it in your own UI by calling `ImGui::DebugStartItemPicker()`.See [#2673](https://github.com/ocornut/imgui/issues/2673) for more details.
-
-![image](https://github.com/ocornut/imgui/assets/8225057/52707662-37c3-4526-a82a-1f2f1daf25dd)
-
-![image](https://github.com/ocornut/imgui/assets/8225057/96828020-215c-4e30-879e-919fb8ea55f3)
-
 ## UTF-8 Encoding Viewer
 
 See https://github.com/ocornut/imgui/blob/master/docs/FONTS.md#about-utf-8-encoding