More documentation for the debugger

Author: grammati

doc/debugging.md

@@ -7,7 +7,7 @@ CIDER ships with a powerful interactive Clojure debugger inspired by Emacs's own
 
 The debugger can be invoked in several ways, the simplest one is to type
 <kbd>C-u C-M-x</kbd>. This will take the current top-level form, place as many
-breakpoints inside it as possible (instrument it), and then evaluate it a
+breakpoints inside it as possible (instrument it), and then evaluate it as
 normal. Whenever a breakpoint is reached, you'll be shown the value and asked
 for input (see below). Note that if the current form is a `defn`, it will stay
 instrumented, so the debugger will be triggered every time the function is
@@ -39,26 +39,105 @@ instrumented as well, but they will not be listed by this command.
 
 ## Keys
 
-`cider-debug` tries to be consistent with
-[Edebug][]. So
-it makes available the following bindings while stepping through code.
+`cider-debug` tries to be consistent with [Edebug][], although there are some
+differences. It makes available the following bindings while stepping through
+code.
 
 Keyboard shortcut               | Description
 --------------------------------|-------------------------------
 <kbd>n</kbd> | Next step
+<kbd>i</kbd> | Step in to a function
+<kbd>o</kbd> | Step out of the current sexp (like `up-list`)
+<kbd>O</kbd> | Force-step out of the current sexp
+<kbd>h</kbd> | Skip all sexps up to “here” (current position). Move the cursor before doing this.
+<kbd>H</kbd> | Force-step to “here”
 <kbd>c</kbd> | Continue without stopping
-<kbd>o</kbd> | Move out of the current sexp (like `up-list`)
-<kbd>i</kbd> | Inject a value into running code
 <kbd>e</kbd> | Eval code in current context
+<kbd>p</kbd> | Inspect a value
 <kbd>l</kbd> | Inspect local variables
+<kbd>j</kbd> | Inject a value into running code
 <kbd>s</kbd> | Show the current stack
-<kbd>h</kbd> | Skip all sexps up to “here” (current position). Move the cursor before doing this.
+<kbd>t</kbd> | Trace. Continue, printing expressions and their values.
 <kbd>q</kbd> | Quit execution
 
 In addition, all the usual evaluation commands (such as <kbd>C-x C-e</kbd> or
 <kbd>C-c M-:</kbd>) will use the current lexical context (local variables) while
 the debugger is active.
 
+## Command Details
+
+Here are some more details about what each of the above commands does.
+
+### Stepping Commands
+
+These commands continue execution until reaching a breakpoint.
+
+In the cider debugger, the term "breakpoint" refers to a place where the
+debugger can halt execution and display the value of an expression. You can set
+a single breakpoint with `#break`, or set breakpoints throughout a form with
+`#dbg` (or by evaluating with `C-u C-M-x`). Not every form is wrapped in a
+breakpoint; the debugger tries to avoid setting breakpoints on expressions that
+would not be interesting to stop at, such as constants. For example, there would
+not be much point in stopping execution at a literal number 23 in your code and
+showing that its value is 23 - you already know that.
+
+- **next**: Steps to the next breakpoint
+- **in**: Steps in to the function about to be called. If the next breakpoint is
+  not around a function call, does the same as `next`. Note that not all
+  functions can be stepped in to - only normal functions stored in vars, for
+  which cider can find the source. You cannot currently step in to multimethods,
+  protocol functions, or functions in clojure.core (although multimethods and
+  protocols can be instrumented manually).
+- **out**: Steps to the next breakpoint that is outside of the current sexp.
+- **Out**: Same as `o`, but skips breakpoints in other functions. That is, if
+  the code being skipped over contains a call to another instrumented function,
+  the debugger will stop in that function if you step out with `o`, but not if
+  you step out with `O`.
+- **here**: Place the point somewhere further on in the function being debugged,
+  at the point where you want to stop next. Then press `h`, and the debugger
+  will skip all breakpoints up until that spot.
+- **Here**: Same as `h`, but skips breakpoints in other functions, as with `O`.
+- **continue**: Continues without stopping, skipping all breakpoints.
+
+### Other Commands
+
+- **eval**: Prompts for a clojure expression, which can reference local
+  variables that are in scope where the debugger is stopped. Displays the result
+  in an overlay.
+- **inspect**: Like eval, but displays the value in a `cider-inspector` buffer.
+- **locals**: Opens a `cider-inspector` buffer displaying all local variables
+  defined in the context where the debugger is stopped.
+- **inject**: Replaces the currently-displayed value with the value of an
+  expression that you type in. Subsequent code will see the new value that you
+  entered.
+- **stacktrace**: Shows the stacktrace of the point where the debugger is
+  stopped.
+- **trace**: Continues execution, but at each breakpoint, instead of stopping
+  and displaying the value in an overlay, prints the form and its value to the
+  REPL.
+- **quit**: Quits execution immediately. Unlike with `continue`, the rest of the
+  code in the debugged function is not executed.
+
+### Conditional Breakpoints
+
+Breakpoints can be conditional, such that the debugger will only stop when the
+condition is true.
+
+Conditions are specified using `:break/when` metadata attached to a form.
+
+```clojure
+(dotimes [i 10]
+  #dbg ^{:break/when (= i 7)}
+  (prn i))
+```
+
+Evaluating the above with `C-M-x`, the debugger will stop only once, when i
+is 7.
+
+You can also have cider insert the break-condition into your code for you. Place
+the point where you want the condition to go and evaluate with `C-u C-u
+C-M-x` or `C-u C-u C-c C-c`.
+
 ## Internal Details
 
 *This section explains a bit of the inner workings of the debugger. It is mostly