tighten some Scribble contracts, improve docs
svn: r8486
This commit is contained in:
Matthew Flatt
parent
96a2baef08
commit
6a8a1557d3
|
|
@ -92,6 +92,11 @@
|
|||
(collect-info-gen-prefix ci))
|
||||
(collect-info-relatives ci)
|
||||
(cons d (collect-info-parents ci)))])
|
||||
(hash-table-put! (collect-info-parts ci)
|
||||
d
|
||||
(make-collected-info number
|
||||
parent
|
||||
(collect-info-ht p-ci)))
|
||||
(when (part-title-content d)
|
||||
(collect-content (part-title-content d) p-ci))
|
||||
(collect-part-tags d p-ci number)
|
||||
|
|
@ -106,11 +111,6 @@
|
|||
number))
|
||||
(loop (cdr parts)
|
||||
(if (unnumbered-part? s) pos (add1 pos))))))
|
||||
(hash-table-put! (collect-info-parts ci)
|
||||
d
|
||||
(make-collected-info number
|
||||
parent
|
||||
(collect-info-ht p-ci)))
|
||||
(let ([prefix (part-tag-prefix d)])
|
||||
(for ([(k v) (collect-info-ht p-ci)])
|
||||
(when (cadr k)
|
||||
|
|
|
|||
|
|
@ -77,13 +77,7 @@
|
|||
|
||||
(provide
|
||||
(struct-out collect-info)
|
||||
(struct-out resolve-info)
|
||||
part-collected-info
|
||||
collect-put!
|
||||
resolve-get
|
||||
resolve-search
|
||||
resolve-get/tentative
|
||||
resolve-get-keys)
|
||||
(struct-out resolve-info))
|
||||
|
||||
;; ----------------------------------------
|
||||
|
||||
|
|
@ -489,5 +483,19 @@
|
|||
|
||||
;; ----------------------------------------
|
||||
|
||||
(define (info-key? l)
|
||||
(and (pair? l)
|
||||
(symbol? (car l))
|
||||
(pair? (cdr l))))
|
||||
|
||||
(provide info-key?)
|
||||
(provide/contract
|
||||
[part-collected-info (part? resolve-info? . -> . collected-info?)]
|
||||
[collect-put! (collect-info? info-key? any/c . -> . any)]
|
||||
[resolve-get ((or/c part? false/c) resolve-info? info-key? . -> . any)]
|
||||
[resolve-get/tentative ((or/c part? false/c) resolve-info? info-key? . -> . any)]
|
||||
[resolve-search (any/c (or/c part? false/c) resolve-info? info-key? . -> . any)]
|
||||
[resolve-get-keys ((or/c part? false/c) resolve-info? (info-key? . -> . any/c) . -> . any/c)])
|
||||
|
||||
)
|
||||
|
||||
|
|
|
|||
|
|
@ -192,7 +192,9 @@ 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].
|
||||
@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.
|
||||
|
||||
Hyperlinks created by @scheme[schememodname] are associated with the
|
||||
enclosing section, rather than the local @scheme[id] text.}
|
||||
|
|
@ -237,7 +239,12 @@ Associates the @scheme[module-paths]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.}
|
||||
hovers the mouse over one of the bindings defined within the section.
|
||||
|
||||
The @scheme[declare-exporting] form should be used no more than once
|
||||
per section, since the declaration applies to the entire section,
|
||||
although overriding @scheme[declare-exporting] forms can appear in
|
||||
sub-sections.}
|
||||
|
||||
@; ------------------------------------------------------------------------
|
||||
@section[#:tag "doc-forms"]{Documenting Forms, Functions, Structure Types, and Values}
|
||||
|
|
|
|||
|
|
@ -65,9 +65,10 @@ A @deftech{flow element} is either a @techlink{table}, an
|
|||
|
||||
@item{An @deftech{element} can be a string, one of a few
|
||||
symbols, an instance of @scheme[element] (possibly
|
||||
@scheme[link-element], etc.), a @techlink{delayed
|
||||
element}, or anything else allowed by the current
|
||||
renderer.
|
||||
@scheme[link-element], etc.), a
|
||||
@techlink{part-relative element}, a
|
||||
@techlink{delayed element}, or anything else
|
||||
allowed by the current renderer.
|
||||
|
||||
@itemize{
|
||||
|
||||
|
|
@ -119,6 +120,17 @@ A @deftech{flow element} is either a @techlink{table}, an
|
|||
processing to record information used by
|
||||
later passes.}
|
||||
|
||||
@item{A @deftech{part-relative element} is an
|
||||
instance of @scheme[part-relative-element],
|
||||
which has a procedure that is called in the
|
||||
@techlink{collect pass} of document
|
||||
processing to obtain @defterm{content} (i.e.,
|
||||
a list of @defterm{elements}). When the
|
||||
part-relative element's procedure is called,
|
||||
collected information is not yet available,
|
||||
but information about the enclosing parts is
|
||||
available.}
|
||||
|
||||
@item{A @deftech{delayed element} is an instance of
|
||||
@scheme[delayed-element], which has a
|
||||
procedure that is called in the
|
||||
|
|
@ -453,15 +465,37 @@ pass}.
|
|||
}
|
||||
|
||||
|
||||
@defstruct[part-relative-element ([resolve (collect-info? . -> . list?)]
|
||||
[sizer (-> any/c)]
|
||||
[plain (-> any/c)])]{
|
||||
|
||||
Similar to @scheme[delayed-flow-element], but the replacement
|
||||
@techlink{content} is obtained in the @techlink{collect pass} by
|
||||
calling the function in the @scheme[resolve] field.
|
||||
|
||||
The @scheme[resolve] function can call @scheme[collect-info-parents]
|
||||
to obtain a list of @techlink{parts} that enclose the element,
|
||||
starting with the nearest enclosing section. Functions like
|
||||
@scheme[part-collected-info] and @scheme[collected-info-number] can
|
||||
extract information like the part number.
|
||||
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(collect-element element) ([collect (collect-info . -> . any)])]{
|
||||
|
||||
Like @scheme[element], but the @scheme[collect] procedure is called
|
||||
during the @techlink{collect pass}. The @scheme[collect] procedure
|
||||
normally calls @scheme[collect-put!].
|
||||
|
||||
Unlike @scheme[delayed-element] or @scheme[part-relative-element], the
|
||||
element remains intact (i.e., it is not replaced) by either the
|
||||
@tech{collect pass} or @tech{resolve pass}.
|
||||
|
||||
}
|
||||
|
||||
|
||||
|
||||
@defstruct[collected-info ([number (listof (or/c false/c integer?))]
|
||||
[parent (or/c false/c part?)]
|
||||
[info any/c])]{
|
||||
|
|
@ -540,11 +574,15 @@ Returns the width in characters of the given @tech{element}.
|
|||
Returns the width in characters of the given @tech{flow element}.}
|
||||
|
||||
|
||||
@defstruct[collect-info ([ht any/c] [ext-ht any/c] [parts any/c] [tags any/c] [gen-prefix any/c])]{
|
||||
@defstruct[collect-info ([ht any/c] [ext-ht any/c] [parts any/c]
|
||||
[tags any/c] [gen-prefix any/c]
|
||||
[relatives any/c]
|
||||
[parents (listof part?)])]{
|
||||
|
||||
Encapsulates information accumulated (or being accumulated) from the
|
||||
@techlink{collect pass}. The fields are exposed, but not currently
|
||||
intended for external use.
|
||||
intended for external use, except that @scheme[collect-info-parents]
|
||||
is intended for external use.
|
||||
|
||||
}
|
||||
|
||||
|
|
@ -556,7 +594,25 @@ intended for external use.
|
|||
|
||||
}
|
||||
|
||||
@defproc[(collect-put! [ci collect-info?] [key any/c] [val any/c])
|
||||
@defproc[(info-key? [v any/c]) boolean?]{
|
||||
|
||||
Returns @scheme[#t] if @scheme[v] is an @deftech{info key}: a list of
|
||||
at least two elements whose first element is a symbol. The result is
|
||||
@scheme[#f] otherwise.
|
||||
|
||||
For a list that is an info tag, the interpretation of the second
|
||||
element of the list is effectively determined by the leading symbol,
|
||||
which classifies the key. However, a @scheme[#f] value as the second
|
||||
element has an extra meaning: collected information mapped by such
|
||||
info keys is not propagated out of the part where it is collected;
|
||||
that is, the information is available within the part and its
|
||||
sub-parts, but not in ancestor or sibling parts.
|
||||
|
||||
Note that every @techlink{tag} is an info key.
|
||||
|
||||
}
|
||||
|
||||
@defproc[(collect-put! [ci collect-info?] [key info-key?] [val any/c])
|
||||
void?]{
|
||||
|
||||
Registers information in @scheme[ci]. This procedure should be called
|
||||
|
|
@ -564,18 +620,48 @@ only during the @techlink{collect pass}.
|
|||
|
||||
}
|
||||
|
||||
@defproc[(resolve-get [p part?] [ri resolve-info?] [key any/c])
|
||||
void?]{
|
||||
@defproc[(resolve-get [p (or/c part? false/c)] [ri resolve-info?] [key info-key?])
|
||||
any/c]{
|
||||
|
||||
Extract information during the @techlink{resolve pass} or
|
||||
@techlink{render pass} for @scheme[p] from @scheme[ri], where the
|
||||
information was previously registered during the @techlink{collect
|
||||
pass}. See also @secref["passes"].
|
||||
|
||||
The result is @scheme[#f] if the no value for the given key is found.
|
||||
Furthermore, the search failure is recorded for potential consistency
|
||||
reporting, such as when @exec{setup-plt} is used to build
|
||||
documentation.
|
||||
|
||||
}
|
||||
|
||||
@defproc[(resolve-get-keys [p part?] [ri resolve-info?]
|
||||
[pred (any/c . -> . any/c)])
|
||||
@defproc[(resolve-search [dep-key any/c][p (or/c part? false/c)] [ri resolve-info?] [key info-key?])
|
||||
void?]{
|
||||
|
||||
Like @scheme[resolve-get], but a shared @scheme[dep-key] groups
|
||||
multiple searches as a single request for the purposes of consistency
|
||||
reporting and dependency tracking. That is, a single success for the
|
||||
same @scheme[dep-key] means that all of the failed attempts for the
|
||||
same @scheme[dep-key] have been satisfied. However, for dependency
|
||||
checking, such as when using @exec{setup-plt} to re-build
|
||||
documentation, all attempts are recorded (in case external changes
|
||||
mean that an earlier attempt would succeed next time).
|
||||
|
||||
}
|
||||
|
||||
@defproc[(resolve-get/tentative [p (or/c part? false/c)] [ri resolve-info?] [key info-key?])
|
||||
any/c]{
|
||||
|
||||
Like @scheme[resolve-search], but without dependency tracking. For
|
||||
multi-document settings where dependencies are normally tracked, such
|
||||
as when using @exec{setup-plt} to build documentation, this function
|
||||
is suitable for use only for information within a single document.
|
||||
|
||||
}
|
||||
|
||||
@defproc[(resolve-get-keys [p (or/c part? false/c)]
|
||||
[ri resolve-info?]
|
||||
[pred (info-key? . -> . any/c)])
|
||||
list?]{
|
||||
|
||||
Applies @scheme[pred] to each key mapped for @scheme[p] in
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user