diff --git a/pkgs/racket-doc/scribblings/reference/eval-model.scrbl b/pkgs/racket-doc/scribblings/reference/eval-model.scrbl index 6d93ff1683..42c89f0def 100644 --- a/pkgs/racket-doc/scribblings/reference/eval-model.scrbl +++ b/pkgs/racket-doc/scribblings/reference/eval-model.scrbl @@ -523,12 +523,13 @@ modules can define the name. That is, a @deftech{module-level variable} is like a @tech{top-level variable} from the perspective of evaluation. -One difference between a module and a top-level definition is that a -module can be declared without instantiating its module-level -definitions. Evaluation of a @racket[require] @deftech{instantiates} -(i.e., triggers the @deftech{instantiation} of) a declared module, -which creates variables that correspond to its module-level -definitions. +One difference between a module and a top-level definition +is that a module can be @deftech[#:key "declare"]{declared} +without instantiating its module-level definitions. +Evaluation of a @racket[require] @deftech{instantiates} +(i.e., triggers the @deftech{instantiation} of) a declared +module, which creates variables that correspond to its +module-level definitions. For example, given the module declaration diff --git a/pkgs/racket-doc/scribblings/reference/module-reflect.scrbl b/pkgs/racket-doc/scribblings/reference/module-reflect.scrbl index 099fcf1fe1..3419cba2cd 100644 --- a/pkgs/racket-doc/scribblings/reference/module-reflect.scrbl +++ b/pkgs/racket-doc/scribblings/reference/module-reflect.scrbl @@ -573,14 +573,19 @@ because the root module does not exist.} Returns information intended to reflect the ``language'' of the implementation of @racket[mod]. If @racket[mod] is a @tech{resolved module path} or @racket[load?] is @racket[#f], the -module named by @racket[mod] must be declared (but not necessarily +module named by @racket[mod] must be @tech{declare}d (but not necessarily @tech{instantiate}d or @tech{visit}ed) in the current namespace; otherwise, @racket[mod] may be loaded (as for @racket[dynamic-require] and other functions). The information returned by @racket[module->language-info] is the same as would have been returned by @racket[module-compiled-language-info] applied to the module's -implementation as compiled code.} +implementation as compiled code. +A module can be @tech{declare}d by using @racket[dynamic-require]. + +@examples[#:eval mod-eval + (dynamic-require 'racket/dict (void)) + (module->language-info 'racket/dict)]} @defproc[(module->imports [mod (or/c module-path? module-path-index? @@ -588,9 +593,19 @@ implementation as compiled code.} (listof (cons/c (or/c exact-integer? #f) (listof module-path-index?)))]{ -Like @racket[module-compiled-imports], but produces the imports of -@racket[mod], which must be declared (but not necessarily -@tech{instantiate}d or @tech{visit}ed) in the current namespace.} + Like @racket[module-compiled-imports], but produces the + imports of @racket[mod], which must be @tech{declare}d (but + not necessarily @tech{instantiate}d or @tech{visit}ed) in + the current namespace. See @racket[module->language-info] for + an example of declaring an existing module. + +@examples[#:eval mod-eval + (module banana racket/base + (require (only-in racket/math pi)) + (provide peel) + (define peel pi) + (define bush (* 2 pi))) + (module->imports ''banana)]} @defproc[(module->exports @@ -598,17 +613,37 @@ Like @racket[module-compiled-imports], but produces the imports of (values (listof (cons/c (or/c exact-integer? #f) list?)) (listof (cons/c (or/c exact-integer? #f) list?)))]{ -Like @racket[module-compiled-exports], but produces the exports of -@racket[mod], which must be declared (but not necessarily -@tech{instantiate}d or @tech{visit}ed) in the current namespace.} + Like @racket[module-compiled-exports], but produces the + exports of @racket[mod], which must be @tech{declare}d (but + not necessarily @tech{instantiate}d or @tech{visit}ed) in + the current namespace. See @racket[module->language-info] for + an example of declaring an existing module. + +@examples[#:eval mod-eval + (module banana racket/base + (require (only-in racket/math pi)) + (provide peel) + (define peel pi) + (define bush (* 2 pi))) + (module->exports ''banana)]} @defproc[(module->indirect-exports [mod (or/c module-path? resolved-module-path?)]) (listof (cons/c exact-integer? (listof symbol?)))]{ -Like @racket[module-compiled-exports], but produces the exports of -@racket[mod], which must be declared (but not necessarily -@tech{instantiate}d or @tech{visit}ed) in the current namespace. + Like @racket[module-compiled-exports], but produces the + exports of @racket[mod], which must be @tech{declare}d (but + not necessarily @tech{instantiate}d or @tech{visit}ed) in + the current namespace. See @racket[module->language-info] for + an example of declaring an existing module. + +@examples[#:eval mod-eval + (module banana racket/base + (require (only-in racket/math pi)) + (provide peel) + (define peel pi) + (define bush (* 2 pi))) + (module->indirect-exports ''banana)] @history[#:added "6.5.0.5"]}