diff --git a/src/jtag/jtag.h b/src/jtag/jtag.h
index f70c1ead8..e5df6619b 100644
--- a/src/jtag/jtag.h
+++ b/src/jtag/jtag.h
@@ -248,11 +248,24 @@ extern int jtag_add_ir_scan(int num_fields, scan_field_t *fields, enum tap_state
 extern int jtag_add_dr_scan(int num_fields, scan_field_t *fields, enum tap_state endstate, void *dummy_anachronism);
 extern int jtag_add_plain_ir_scan(int num_fields, scan_field_t *fields, enum tap_state endstate, void *dummy_anachronism);
 extern int jtag_add_plain_dr_scan(int num_fields, scan_field_t *fields, enum tap_state endstate, void *dummy_anachronism);
-/* execute a state transition within the JTAG standard, but nothing is defined
- * w.r.t. the path that is taken. Many implementations use precisely
+/* execute a state transition within the JTAG standard, but the exact path
+ * path that is taken is undefined. Many implementations use precisely
  * 7 clocks to perform a transition, but it could be more or less
  * than that.
- */
+ *
+ * The following assertions are made about certain common state moves:
+ *
+ * - A state move from Pause-[ID]R to Pause-[ID]R should always go through 
+ *   Update-[ID]R and Capture-[ID]R before returning to Pause-[ID]R, otherwise 
+ *   there's no way force a register update, if you can't go to Run-Test/Idle for 
+ *   some reason.
+ *
+ *   - A state move from Pause-[ID]R to Shift-[ID]R must not go through 
+ *   Update-[ID]R.
+ *
+ *   - Run-Test/Idle must not be entered unless requested, because R-T/I may have 
+ *   side effects.
+ */
 extern int jtag_add_statemove(enum tap_state endstate);
 /* A list of unambigious single clock state transitions, not
  * all drivers can support this, but it is required for e.g.