diff --git a/collects/scribble/extract.rkt b/collects/scribble/extract.rkt index 11661a93..6ce0e029 100644 --- a/collects/scribble/extract.rkt +++ b/collects/scribble/extract.rkt @@ -22,10 +22,11 @@ #'(xwrap (... ...) id)) ;; delayed: (with-syntax ([(_ xwrap (... ...)) stx] - [(reqs ((id d) (... ...))) (syntax-local-introduce - (datum->syntax #f (get-docs)))]) + [(reqs exprs ((id d) (... ...))) (syntax-local-introduce + (datum->syntax #f (get-docs)))]) #`(begin (require . reqs) + (begin . exprs) (xwrap (... ...) (list (cons 'id d) (... ...))))))) (docs wrap ...)))])) diff --git a/collects/scribble/srcdoc.rkt b/collects/scribble/srcdoc.rkt index 77b0c5ce..e79b976e 100644 --- a/collects/scribble/srcdoc.rkt +++ b/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 ...)) diff --git a/collects/scribblings/scribble/srcdoc.scrbl b/collects/scribblings/scribble/srcdoc.scrbl index c64cc570..8d9c7b2e 100644 --- a/collects/scribblings/scribble/srcdoc.scrbl +++ b/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