scribble/srcdoc: add `begin-for-doc'

original commit: 9e0e2b932d09a30c8a09d1ab599cebc5e6d964c9

collects/scribble/extract.rkt

@@ -22,10 +22,11 @@
                    #'(xwrap (... ...) id))
                  ;; delayed:
                  (with-syntax ([(_ xwrap (... ...)) stx]
-                               [(reqs ((id d) (... ...))) (syntax-local-introduce
+                               [(reqs exprs ((id d) (... ...))) (syntax-local-introduce
-                                                           (datum->syntax #f (get-docs)))])
+                                                                 (datum->syntax #f (get-docs)))])
                    #`(begin
                        (require . reqs)
+                       (begin . exprs)
                        (xwrap (... ...) (list (cons 'id d) (... ...)))))))
            (docs wrap ...)))]))
 

collects/scribble/srcdoc.rkt

@@ -11,11 +11,13 @@
          parameter-doc
          proc-doc
          proc-doc/names
-         generate-delayed-documents)
+         generate-delayed-documents
+         begin-for-doc)
 
 (begin-for-syntax
  (define requires null)
  (define doc-body null)
+ (define doc-exprs null)
  (define generated? #f)
  (define delayed? #f)
 
@@ -59,6 +61,7 @@
 (define-syntax (doc-submodule stx)
   (with-syntax ([((req ...) ...)
                  (map syntax-local-introduce (reverse requires))]
+                [(expr ...) (map syntax-local-introduce (reverse doc-exprs))]
                 [doc-body
                  (map (lambda (s) (syntax-local-introduce
                                    (syntax-shift-phase-level s #f)))
@@ -73,12 +76,14 @@
               (provide get-docs)
               (define (get-docs)
                 (list (quote-syntax (req ... ...))
+                      (quote-syntax (expr ...))
                       (quote-syntax/keep-srcloc doc-body))))))
         ;; normal mode: return an identifier that holds the document:
         (with-syntax ([((id d) ...) #'doc-body])
           #'(begin-for-syntax
              (module* srcdoc #f
                (require req ... ...)
+               expr ...
                (define docs (list (cons 'id d) ...))
                (require (for-syntax racket/base))
                (begin-for-syntax
@@ -131,6 +136,15 @@
         (set! requires (cons #'(req ... ...) requires))
         (pre-expand-export #'(combine-out p/c ...) modes)))))
 
+(define-syntax (begin-for-doc stx)
+  (syntax-case stx ()
+    [(_ d ...)
+     (set! doc-exprs (append (reverse (syntax->list 
+                                       (syntax-local-introduce
+                                        #'(d ...))))
+                             doc-exprs))
+     #'(begin)]))
+
 (define-syntax-rule (provide/doc form ...)
   (provide form ...))
 

collects/scribblings/scribble/srcdoc.scrbl

@@ -63,7 +63,7 @@ to get core Racket forms and basic Scribble functions to use in
 documentation expressions.}
 
 @defform*/subs[#:literals (-> ->* case->)
-               [(proc-doc/names id contract arg-specs desc-expr)]
+               [(proc-doc/names id contract arg-specs (desc-expr ...))]
                ([arg-specs ((arg-id ...) ((arg-id default-expr) ...))
                            (arg-id ...)]
                 [contract (-> arg ... result)
@@ -87,7 +87,7 @@ pairs specify the names and default values of the optional arguments.
 If the contract supports optional arguments, then the first
 @racket[arg-spec]s form must be used, otherwise the second must be used.
 
-The @racket[desc-expr] is a documentation-time expression that
+The @racket[desc-expr] is a sequence of documentation-time expressions that
 produces prose to describe the exported binding---that is, the last
 part of the generated @racket[defproc], so the description can refer
 to the @racket[arg-id]s using @racket[racket].
@@ -101,7 +101,7 @@ can be referenced in documentation prose using the @racket[racket]
 form.}
 
 @defform/subs[#:literals (-> ->i ->d values)
-              (proc-doc id contract desc-expr)
+              (proc-doc id contract (desc-expr ...))
               ([contract (-> result)
                          (->i (arg ...) () (values ress ...))
                          (->i (arg ...) () #:pre (pre-id ...) condition (values ress ...))
@@ -126,11 +126,22 @@ Like @racket[proc-doc], but for an export of an arbitrary value.}
 
 
 @defform[#:literals (parameter/c)
-         (parameter-doc id (parameter/c contract-expr) arg-id desc-expr)]{
+         (parameter-doc id (parameter/c contract-expr) arg-id (desc-expr ...))]{
 
 Like @racket[proc-doc], but for exporting a parameter.}
 
 
+@defform[(begin-for-doc form ...)]{
+
+Like to @racket[begin-for-syntax], but for documentation time instead
+of expansion time. The @racket[form]s can refer to binding
+@racket[require]d with @racket[for-doc].
+
+For example, a definition in @racket[begin-for-doc]
+can be referenced by a @racket[_desc-expr] in
+@racket[proc-doc/names].}
+
+
 @defform[(generate-delayed-documents)]{
 
 Causes documentation information to be recorded as a macro that is