add #:use-sources to Scribble module declarations, so that scheme/base and mzscheme can better share documentation; finish documenting legacy mzscheme bindings
svn: r8538 original commit: 794e6c8a398da5857097795ff5c8d022bf55fed2
This commit is contained in:
Matthew Flatt
parent
57b8baeb1c
commit
c0c97a6090
|
|
@ -108,10 +108,15 @@
|
|||
#f
|
||||
(list . content)))
|
||||
|
||||
(define-syntax-rule (defmodule* (name ...) . content)
|
||||
(begin
|
||||
(declare-exporting name ...)
|
||||
(defmodule*/no-declare (name ...) . content)))
|
||||
(define-syntax defmodule*
|
||||
(syntax-rules ()
|
||||
[(_ (name ...) #:use-sources (pname ...) . content)
|
||||
(begin
|
||||
(declare-exporting name ... #:use-sources (pname ...))
|
||||
(defmodule*/no-declare (name ...) . content))]
|
||||
[(_ (name ...) . content)
|
||||
(defmodule* (name ...) #:use-sources () . content)]))
|
||||
|
||||
|
||||
(define-syntax-rule (defmodule name . content)
|
||||
(defmodule* (name) . content))
|
||||
|
|
@ -121,10 +126,14 @@
|
|||
#t
|
||||
(list . content)))
|
||||
|
||||
(define-syntax-rule (defmodulelang* (name ...) . content)
|
||||
(begin
|
||||
(declare-exporting name ...)
|
||||
(defmodulelang*/no-declare (name ...) . content)))
|
||||
(define-syntax defmodulelang*
|
||||
(syntax-rules ()
|
||||
[(_ (name ...) #:use-sources (pname ...) . content)
|
||||
(begin
|
||||
(declare-exporting name ... #:use-sources (pname ...))
|
||||
(defmodulelang*/no-declare (name ...) . content))]
|
||||
[(_ (name ...) . content)
|
||||
(defmodulelang* (name ...) #:use-sources () . content)]))
|
||||
|
||||
(define-syntax-rule (defmodulelang lang . content)
|
||||
(defmodulelang* (lang) . content))
|
||||
|
|
@ -338,14 +347,38 @@
|
|||
(annote-exporting-library
|
||||
(to-element (make-just-context name stx-id))))))
|
||||
|
||||
(define (libs->taglet libs)
|
||||
(and (pair? libs)
|
||||
(let ([p (resolved-module-path-name
|
||||
(module-path-index-resolve
|
||||
(module-path-index-join (car libs) #f)))])
|
||||
(if (path? p)
|
||||
(intern-taglet (path->main-collects-relative p))
|
||||
p))))
|
||||
(define checkers (make-hash-table 'equal))
|
||||
|
||||
(define (libs->taglet id libs source-libs)
|
||||
(let ([lib
|
||||
(or (ormap (lambda (lib)
|
||||
(let ([checker (hash-table-get checkers lib
|
||||
(lambda ()
|
||||
(let ([ns (make-base-empty-namespace)])
|
||||
(parameterize ([current-namespace ns])
|
||||
(namespace-require `(for-label ,lib)))
|
||||
(let ([checker
|
||||
(lambda (id)
|
||||
(parameterize ([current-namespace ns])
|
||||
(let ([new-id (namespace-syntax-introduce
|
||||
(datum->syntax
|
||||
#f
|
||||
(syntax-e id)))])
|
||||
(free-label-identifier=? new-id id))))])
|
||||
(hash-table-put! checkers lib checker)
|
||||
checker))))])
|
||||
(and (checker id)
|
||||
lib)))
|
||||
source-libs)
|
||||
(and (pair? libs)
|
||||
(car libs)))])
|
||||
(and lib
|
||||
(let ([p (resolved-module-path-name
|
||||
(module-path-index-resolve
|
||||
(module-path-index-join lib #f)))])
|
||||
(if (path? p)
|
||||
(intern-taglet (path->main-collects-relative p))
|
||||
p)))))
|
||||
|
||||
(define (id-to-target-maker id dep?)
|
||||
(*id-to-target-maker 'def id dep?))
|
||||
|
|
@ -373,7 +406,11 @@
|
|||
"no declared exporting libraries for definition"
|
||||
id)))
|
||||
(if e
|
||||
(let* ([lib-taglet (libs->taglet (exporting-libraries-libs e))]
|
||||
(let* ([lib-taglet (libs->taglet (if sig
|
||||
(sig-id sig)
|
||||
id)
|
||||
(exporting-libraries-libs e)
|
||||
(exporting-libraries-source-libs e))]
|
||||
[tag (list (if sig
|
||||
(case sym
|
||||
[(def) 'sig-val]
|
||||
|
|
@ -529,11 +566,12 @@
|
|||
|
||||
(define-syntax declare-exporting
|
||||
(syntax-rules ()
|
||||
[(_ lib ...) (*declare-exporting '(lib ...))]))
|
||||
[(_ lib ... #:use-sources (plib ...)) (*declare-exporting '(lib ...) '(plib ...))]
|
||||
[(_ lib ...) (*declare-exporting '(lib ...) '())]))
|
||||
|
||||
(define-struct (exporting-libraries element) (libs))
|
||||
(define-struct (exporting-libraries element) (libs source-libs))
|
||||
|
||||
(define (*declare-exporting libs)
|
||||
(define (*declare-exporting libs source-libs)
|
||||
(make-splice
|
||||
(list
|
||||
(make-part-collect-decl
|
||||
|
|
@ -542,7 +580,7 @@
|
|||
(lambda (ri)
|
||||
(collect-put! ri '(exporting-libraries #f) libs))))
|
||||
(make-part-collect-decl
|
||||
(make-exporting-libraries #f null libs)))))
|
||||
(make-exporting-libraries #f null libs source-libs)))))
|
||||
|
||||
(define-syntax (quote-syntax/loc stx)
|
||||
(syntax-case stx ()
|
||||
|
|
|
|||
|
|
@ -184,7 +184,8 @@ in a form definition.}
|
|||
@; ------------------------------------------------------------------------
|
||||
@section[#:tag "doc-modules"]{Documenting Modules}
|
||||
|
||||
@defform[(defmodule id pre-flow ...)]{
|
||||
@defform/subs[(defmodule id maybe-sources pre-flow ...)
|
||||
([maybe-sources #:use-sources (mod-path ...)])]
|
||||
|
||||
Produces a sequence of flow elements (encaptured in a @scheme[splice])
|
||||
to start the documentation for a module that can be @scheme[require]d
|
||||
|
|
@ -192,27 +193,29 @@ using the path @scheme[id]. The @tech{decode}d @scheme[pre-flow]s
|
|||
introduce the module, but need not include all of the module content.
|
||||
|
||||
Besides generating text, this form expands to a use of
|
||||
@scheme[declare-exporting] with @scheme[id]. Consequently,
|
||||
@scheme[defmodule] should be used at most once in a section, though it
|
||||
can be shadowed with @scheme[defmodule]s in sub-sections.
|
||||
@scheme[declare-exporting] with @scheme[id]; the
|
||||
@scheme[#:use-sources] clause, if provided, is propagated to
|
||||
@scheme[declare-exporting]. Consequently, @scheme[defmodule] should be
|
||||
used at most once in a section, though it can be shadowed with
|
||||
@scheme[defmodule]s in sub-sections.
|
||||
|
||||
Hyperlinks created by @scheme[schememodname] are associated with the
|
||||
enclosing section, rather than the local @scheme[id] text.}
|
||||
|
||||
|
||||
@defform[(defmodulelang id pre-flow ...)]{
|
||||
@defform[(defmodulelang id maybe-sources pre-flow ...)]{
|
||||
|
||||
Like @scheme[defmodule], but documents @scheme[id] as a module path
|
||||
suitable for use by either @scheme[require] or @schememodfont{#lang}.}
|
||||
|
||||
|
||||
@defform[(defmodule* (id ...) pre-flow ...)]{
|
||||
@defform[(defmodule* (id ...) maybe-sources pre-flow ...)]{
|
||||
|
||||
Like @scheme[defmodule], but introduces multiple module paths instead
|
||||
of just one.}
|
||||
|
||||
|
||||
@defform[(defmodulelang* (id ...) pre-flow ...)]{
|
||||
@defform[(defmodulelang* (id ...) maybe-sources pre-flow ...)]{
|
||||
|
||||
Like @scheme[defmodulelang], but introduces multiple module paths
|
||||
instead of just one.}
|
||||
|
|
@ -233,13 +236,36 @@ Like @scheme[defmodulelang*], but without expanding to
|
|||
@scheme[declare-exporting].}
|
||||
|
||||
|
||||
@defform[(declare-exporting module-path ...)]{
|
||||
|
||||
Associates the @scheme[module-paths]s to all bindings defined within
|
||||
the enclosing section, except as overridden by other
|
||||
@defform/subs[(declare-exporting mod-path ... maybe-sources)
|
||||
([maybe-sources #:use-sources (mod-path ...)])]{
|
||||
|
||||
Associates the @scheme[mod-path]s to all bindings defined within the
|
||||
enclosing section, except as overridden by other
|
||||
@scheme[declare-exporting] declarations in nested sub-sections. The
|
||||
list of @scheme[module-path]s is shown, for example, when the user
|
||||
hovers the mouse over one of the bindings defined within the section.
|
||||
list of @scheme[mod-path]s is shown, for example, when the user hovers
|
||||
the mouse over one of the bindings defined within the section.
|
||||
|
||||
More significantly, the first @scheme[mod-path] plus the
|
||||
@scheme[#:use-sources] @scheme[mod-path]s determine the binding that
|
||||
is documented by each @scheme[defform], @scheme[defproc], or similar
|
||||
form within the section that contains the @scheme[declare-exporting]
|
||||
declaration:
|
||||
|
||||
@itemize{
|
||||
|
||||
@item{If no @scheme[#:use-sources] clause is supplied, then the
|
||||
documentation applies to the given name as exported by the first
|
||||
@scheme[mod-path].}
|
||||
|
||||
@item{If @scheme[#:use-sources] @scheme[mod-path]s are supplied, then
|
||||
they are tried in order. The first one to provide an export
|
||||
with the same symbolic name and
|
||||
@scheme[free-label-identifier=?] to the given name is used as
|
||||
the documented binding. This binding is assumed to be the same
|
||||
as the identifier as exported by the first @scheme[mod-path] in
|
||||
the @scheme[declare-exporting] declaration.}
|
||||
|
||||
}
|
||||
|
||||
The @scheme[declare-exporting] form should be used no more than once
|
||||
per section, since the declaration applies to the entire section,
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user