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

scribble: clarify intent of `#:use-sources'

Browse Source 
original commit: 5d06476cb3f91c7dbd370b1e24a5454cb4dd1229
This commit is contained in:
Matthew Flatt 2011-07-05 07:01:50 -06:00
parent 5086963aa8
commit 19221251c7
1 changed files with 46 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
collects/scribblings/scribble/manual.scrbl
View File

@ -481,14 +481,15 @@ and one that combines several modules) via your own
Associates the @racket[mod-path]s to all bindings defined within the Associates the @racket[mod-path]s to all bindings defined within the
enclosing section, except as overridden by other enclosing section, except as overridden by other
@racket[declare-exporting] declarations in nested sub-sections. The @racket[declare-exporting] declarations in nested sub-sections. The
list of @racket[mod-path]s is shown, for example, when the user hovers list of @racket[mod-path]s before @racket[#:use-sources] is shown, for
the mouse over one of the bindings defined within the section. example, when the user hovers the mouse over one of the bindings
defined within the section.
More significantly, the first @racket[mod-path] plus the More significantly, the first @racket[mod-path] before
@racket[#:use-sources] @racket[mod-path]s determine the binding that @racket[#:use-sources] plus the @racket[mod-path]s after
is documented by each @racket[defform], @racket[defproc], or similar @racket[#:use-sources] determine the binding that is documented by
form within the section that contains the @racket[declare-exporting] each @racket[defform], @racket[defproc], or similar form within the
declaration: section that contains the @racket[declare-exporting] declaration:
@itemize[ @itemize[
@ -497,15 +498,47 @@ declaration:
@racket[mod-path].} @racket[mod-path].}
@item{If @racket[#:use-sources] @racket[mod-path]s are supplied, then @item{If @racket[#:use-sources] @racket[mod-path]s are supplied, then
they are tried in order. The first one to provide an export they are tried in order before the first @racket[mod-path]. The
with the same symbolic name and @racket[mod-path] that provides an export with the same
@racket[free-label-identifier=?] to the given name is used as symbolic name and @racket[free-label-identifier=?] to the given
the documented binding. This binding is assumed to be the same name is used as the documented binding. This binding is assumed
as the identifier as exported by the first @racket[mod-path] in to be the same as the identifier as exported by the first
the @racket[declare-exporting] declaration.} @racket[mod-path] in the @racket[declare-exporting]
declaration.}
] ]
Use @racket[#:use-sources] sparingly, but it is needed when
@itemlist[
@item{bindings are documented as originating from a module
@racket[_M], but the bindings are actually re-exported from
some module @racket[_P]; and}
@item{other documented modules also re-export the bindings from
@racket[_P], but they are documented as re-exporting from
@racket[_M].}
]
For example, the @racket[parameterize] binding of
@racketmodname[mzscheme] is documented as re-exported from
@racketmodname[racket/base], but @racket[parameterize] happens to be
implemented in a private module and re-exported by both
@racketmodname[racket/base] and @racketmodname[mzscheme]. Importing
@racket[parameterize] from @racketmodname[mzscheme] does not go
through @racketmodname[racket/base], so a search for documentation on
@racket[parameterize] in @racketmodname[mzscheme] would not
automatically connect to the documentation of
@racketmodname[racket/base]. To make the connection, the documentation
of @racketmodname[racket/base] declares the private module to be a
source through @racket[#:use-sources], so that any re-export of
@racket[parameterize] from the private module connects to the
documentation for @racketmodname[racket/base] (unless a re-export has
its own documentation, which would override the automatic connection
when searching for documentation).
The initial @racket[mod-path]s sequence can be empty if The initial @racket[mod-path]s sequence can be empty if
@racket[mod-path]s are given with @racket[#:use-sources]. In that @racket[mod-path]s are given with @racket[#:use-sources]. In that
case, the rendered documentation never reports an exporting module for case, the rendered documentation never reports an exporting module for