docs(debugger): add hacks, dap overview, basic usage info

Close: #6605
Co-authored-by: rittelle <rittelle@users.noreply.github.com>

modules/tools/debugger/README.org

@@ -1,5 +1,5 @@
 #+title:    :tools debugger
-#+subtitle: Step through code to help you add bugs
+#+subtitle: Step through code to add more bugs
 #+created:  February 20, 2020
 #+since:    2.0.0
 
@@ -23,10 +23,11 @@ there is still not *enough* documentation for it.
   - [[doom-package:dap-mode]] 
   - [[doom-package:posframe]] 
 
-** TODO Hacks
-#+begin_quote
- 🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
-#+end_quote
+** Hacks
+- Enables ~gdb-many-windows-mode~ in ~gdb-mode~ by default
+- Patches [[doom-package:realgud]] to open in a popup window. This causes realgud
+  bindings to focus the command window.
+- Closes [[doom-package:realgud]]'s command buffer after the session ends.
 
 ** TODO Changelog
 # This section will be machine generated. Don't edit it by hand.
@@ -61,51 +62,83 @@ You need this if you are having ~"wrong-type-argument stringp nil"~ error when
 calling ~dap-gdb-lldb-setup~. [[github:emacs-lsp/dap-mode/issues/313][See emacs-lsp/dap-mode#313]]
 
 ** DAP debuggers
-*** Python
-DAP expects [[https://github.com/Microsoft/ptvsd][ptvsd]] by default as the Python debugger, but [[https://github.com/microsoft/debugpy][debugpy]] is recommended.
-See [[*Configuration][Configuration]].
+*** dap-cpptools
+- Languages: C, C++, Rust
+- Documentation
+  - [[https://code.visualstudio.com/docs/cpp/cpp-debug][adapter]]
+  - [[https://emacs-lsp.github.io/dap-mode/page/configuration/#vscode-cpptools][dap-mode configuration]]
 
-*installing ptvsd:*
-#+begin_src sh
-pip3 install ptvsd --user
-#+end_src
+Run =M-x dap-cpptools-setup= to setup the adapter before using it the first
+time.
 
-*install debugpy:*
+*** dap-gdb-lldb
+- Languages: C, C++, Rust
+- Documentation
+  - [[https://github.com/WebFreak001/code-debug][adapter]]
+  - [[https://emacs-lsp.github.io/dap-mode/page/configuration/#native-debug-gdblldb][dap-mode configuration]]
+
+Install the vscode extension using =M-x dap-gdb-lldb-setup= before using it the
+first time.
+
+*** dap-lldb
+- Languages: C, C++, Rust
+- Documentation
+  - [[https://github.com/llvm/llvm-project/tree/main/lldb/tools/lldb-vscode][adapter]]
+  - [[https://emacs-lsp.github.io/dap-mode/page/configuration/#lldb][dap-mode configuration]]
+
+Needs [[https://github.com/llvm/llvm-project/tree/main/lldb/tools/lldb-vscode][lldb-vscode]]. Install LLDB from your package manager. For example:
+
+- *Arch Linux:* ~$ pacman -S lldb~
+- *Fedora:* ~$ dnf install lldb~
+
+*** dap-python
+- Languages: Python
+- Documentation:
+  - [[https://github.com/microsoft/debugpy/][adapter]]
+  - [[https://emacs-lsp.github.io/dap-mode/page/configuration/#python][dap-mode configuration]]
+
+By default, DAP expects [[https://github.com/Microsoft/ptvsd][ptvsd]] as the Python debugger, but [[https://github.com/microsoft/debugpy][debugpy]] is
+recommended. See [[*Configuration][Configuration]].
+
+*installing ptvsd and debugpy:*
 #+begin_src sh
-pip3 install debugpy --user
+$ pip3 install ptvsd --user
+$ pip3 install debugpy --user
 #+end_src
 
 #+begin_src emacs-lisp
 ;; in $DOOMDIR/config.el
 (after! dap-mode
   (setq dap-python-debugger 'debugpy))
-#+end_src
+#+end_src* TODO Usage
 
-*** C, C++, Rust, Golang
-Needs [[https://github.com/llvm/llvm-project/tree/main/lldb/tools/lldb-vscode][lldb-vscode]]. Install LLDB from your package manager.
+* Usage
+Start a debugging session with ~M-x +debugger/start~ (bound to [[kbd:][SPC o d]] in evil).
+You'll be prompted to select a debugger preset if this is the first time you've
+used it. Otherwise, it will use the last preset automatically. Use the
+universal/prefix argument to invoke this prompt again: [[kbd:][SPC u SPC o d]] or [[kbd:][C-u C-c
+o d]]. The last used configuration is stored for each project individually.
 
-*Fedora:*
-#+begin_src sh
-dnf install lldb
-#+end_src
+~M-x +debugger/start-last~ starts the last used debug configuration, if it
+exists, and prints a message otherwise instead of offering a selection.
 
-* TODO Usage
+Once the session is started, it can be terminated by ~M-x +debugger/quit~ or by
+using the mode-specific way.
+
+** TODO realgud
 #+begin_quote
- 🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
+ 🔨 Instructions for realgud haven't been written yet. [[doom-contrib-module:][Write some?]]
 #+end_quote
 
-- ~M-x +debugger/start~
-- ~M-x +debugger/start-last~
-- ~M-x +debugger/quit~
-  
-** Realgud
+** dap-mode
+*** How to add a debug configuration
 1. Call ~dap-gdb-lldb-setup~ function.
 2. Use ~dap-debug-edit-template~ to configure debugging settings for your
    project. [[github:WebFreak001/code-debug/blob/master/package.json#L72][Available settings can be inspected here.]] Call ~eval-buffer~ to save
    your settings. *Don't save the file!*
 3. Call ~dap-debug~, select a configuration and start debugging.
 
-** dap-mode with ~+lsp~
+*** dap-mode with ~+lsp~
 Intuitive and powerful debugging.
 
 - Breakpoints
@@ -116,6 +149,20 @@ Intuitive and powerful debugging.
   expressions.
   
 ** Keybindings
+
+*** General
+| Keybind | Description              |
+|---------+--------------------------|
+| [[kbd:][SPC o d]] | Start a debugger session |
+
+*** dap-mode
+When a dap-mode session is running, the following mappings are active:
+
+| Keybind | Description                      |
+|---------+----------------------------------|
+| [[kbd:][SPC m d]] | Open a hydra for session control |
+
+The hydra is defined as follows:
 #+begin_src emacs-lisp
 (map! :map dap-mode-map
       :leader
@@ -161,6 +208,9 @@ Intuitive and powerful debugging.
 * Frequently asked questions
 /This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
 
+** Setting breakpoints in realgud does not work outside a session
+This currently is not supported by realgud.
+
 * TODO Appendix
 #+begin_quote
  🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]