commit 4cbccb1c85af929f3698a4071969017e0bbf2362
parent ef2005e586dcb2d19e1eaced07a7f04fc4e05492
Author: Matthew Flatt <mflatt@racket-lang.org>
Date: Wed, 6 Mar 2013 06:19:46 -0700
scribble/srcdoc: add `begin-for-doc'
original commit: 9e0e2b932d09a30c8a09d1ab599cebc5e6d964c9
Diffstat:
3 files changed, 33 insertions(+), 7 deletions(-)
diff --git 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
@@ -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
@@ -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
