From c0c97a60904258509a49612fa749ec7a56a2d83d Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Tue, 5 Feb 2008 16:33:26 +0000 Subject: [PATCH] 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 --- collects/scribble/manual.ss | 80 ++++++++++++++++------ collects/scribblings/scribble/manual.scrbl | 52 ++++++++++---- 2 files changed, 98 insertions(+), 34 deletions(-) diff --git a/collects/scribble/manual.ss b/collects/scribble/manual.ss index 77b6fbc9..daf0434b 100644 --- a/collects/scribble/manual.ss +++ b/collects/scribble/manual.ss @@ -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 () diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl index b84632be..b6306d14 100644 --- a/collects/scribblings/scribble/manual.scrbl +++ b/collects/scribblings/scribble/manual.scrbl @@ -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,