macro-stepper: added docs for macro-debugger/emit

original commit: 70fedd766f94bc6c7773c1864e2f6f8462d71d69

collects/macro-debugger/macro-debugger.scrbl

@@ -4,6 +4,7 @@
           scribble/eval
           (for-label scheme/base
                      macro-debugger/expand
+                     macro-debugger/emit
                      macro-debugger/stepper
                      macro-debugger/stepper-text
                      macro-debugger/syntax-browser
@@ -101,6 +102,47 @@ thing as the original syntax.
                (lambda (id) (memq (syntax-e id) '(or #%app))))))
 }
 
+
+@section{Macro stepper API for macros}
+
+@defmodule[macro-debugger/emit]
+
+Macros can explicitly send information to a listening macro stepper by
+using the procedures in this module.
+
+@defproc[(emit-remark [fragment (or/c syntax? string?)] ...
+                      [#:unmark? unmark? boolean? #t])
+         void?]{
+
+Emits an event to the macro stepper (if one is listening) containing
+the given strings and syntax objects. The macro stepper displays a
+remark by printing the strings and syntax objects above a rendering of
+the macro's context. The remark is only displayed if the macro that
+emits it is considered transparent by the hiding policy.
+
+By default, syntax objects in remarks have the transformer's mark
+applied (using @scheme[syntax-local-introduce]) so that their
+appearance in the macro stepper matches their appearance after the
+transformer returns. Unmarking is suppressed if @scheme[unmark?] is
+@scheme[#f].
+
+@schemeblock[
+(define-syntax (mymac stx)
+  (syntax-case stx ()
+    [(_ x y)
+     (emit-remark "I got some arguments!"
+                  #'x
+                  "and"
+                  #'y)
+     #'(list 'x 'y)]))
+(mymac 37 (+ 1 2))
+]
+
+(Run the fragment above in the macro stepper.)
+
+}
+
+
 @section{Macro stepper text interface}
 
 @defmodule[macro-debugger/stepper-text]