suzanne.soy/scribble-enhanced
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

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

Browse Source 
original commit: 9e0e2b932d09a30c8a09d1ab599cebc5e6d964c9
This commit is contained in:
Matthew Flatt 2013-03-06 06:19:46 -07:00
parent ef2005e586
commit 4cbccb1c85
3 changed files with 33 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
collects/scribble/extract.rkt
View File

@ -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 ...)))]))

16
collects/scribble/srcdoc.rkt
View File

@ -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 ...))

19
collects/scribblings/scribble/srcdoc.scrbl
View File

@ -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