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

improced scribble class/interface doc forms

Browse Source 
svn: r7284

original commit: 93cc35bd5bbc419650b2c9a85dfce555658dfdb4
This commit is contained in:
Matthew Flatt 2007-09-06 13:19:15 +00:00
parent a16a3fbfba
commit 742e7820fa
6 changed files with 314 additions and 231 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
collects/scribble/base-render.ss
View File

@ -278,11 +278,7 @@
[(element? i) [(element? i)
(cond (cond
[(link-element? i) [(link-element? i)
(let-values ([(dest ext?) (resolve-get/where d ri (link-element-tag i))]) (resolve-get d ri (link-element-tag i))])
(when ext?
(hash-table-put! (resolve-info-undef ri)
(tag-key (link-element-tag i) ri)
#t)))])
(for-each (lambda (e) (for-each (lambda (e)
(resolve-element e d ri)) (resolve-element e d ri))
(element-content i))])) (element-content i))]))

13
collects/scribble/html-render.ss
View File

@ -150,8 +150,17 @@
,@(render-onthispage-contents d ri top) ,@(render-onthispage-contents d ri top)
,@(apply append ,@(apply append
(map (lambda (t) (map (lambda (t)
(render-table t d ri)) (let loop ([t t])
(filter auxiliary-table? (flow-paragraphs (part-flow d))))))))) (if (table? t)
(render-table t d ri)
(loop (delayed-flow-element-flow-elements t ri)))))
(filter (lambda (e)
(let loop ([e e])
(or (and (auxiliary-table? e)
(pair? (table-flowss e)))
(and (delayed-flow-element? e)
(loop (delayed-flow-element-flow-elements e ri))))))
(flow-paragraphs (part-flow d)))))))))
(define/private (render-onthispage-contents d ri top) (define/private (render-onthispage-contents d ri top)
(if (ormap (lambda (p) (part-whole-page? p ri)) (if (ormap (lambda (p) (part-whole-page? p ri))

411
collects/scribble/manual.ss
View File

@ -8,7 +8,8 @@
(lib "string.ss") (lib "string.ss")
(lib "list.ss") (lib "list.ss")
(lib "class.ss") (lib "class.ss")
(lib "stxparam.ss")) (lib "stxparam.ss")
(lib "serialize.ss"))
(require-for-syntax (lib "stxparam.ss")) (require-for-syntax (lib "stxparam.ss"))
(require-for-label (lib "lang.ss" "big") (require-for-label (lib "lang.ss" "big")
(lib "class.ss")) (lib "class.ss"))
@ -214,14 +215,15 @@
(elem (method a b) " in " (scheme a))])) (elem (method a b) " in " (scheme a))]))
(define (*method sym id) (define (*method sym id)
(let ([tag (method-tag (register-scheme-definition id #t) (**method sym (register-scheme-definition id #t)))
sym)])
(make-element (define (**method sym tag)
"schemesymbol" (make-element
(list (make-link-element "schemesymbol"
"schemevaluelink" (list (make-link-element
(list (symbol->string sym)) "schemevaluelink"
tag))))) (list (symbol->string sym))
(method-tag tag sym)))))
(define (method-tag vtag sym) (define (method-tag vtag sym)
(list 'meth (list 'meth
@ -376,7 +378,7 @@
[(_ name ([field field-contract] ...) immutable? transparent? desc ...) [(_ name ([field field-contract] ...) immutable? transparent? desc ...)
(*defstruct (quote-syntax/loc name) 'name (*defstruct (quote-syntax/loc name) 'name
'([field field-contract] ...) (list (lambda () (schemeblock0 field-contract)) ...) '([field field-contract] ...) (list (lambda () (schemeblock0 field-contract)) ...)
#t #t (lambda () (list desc ...)))])) immutable? transparent? (lambda () (list desc ...)))]))
(define-syntax (defform*/subs stx) (define-syntax (defform*/subs stx)
(syntax-case stx () (syntax-case stx ()
[(_ #:literals (lit ...) [spec spec1 ...] ([non-term-id non-term-form ...] ...) desc ...) [(_ #:literals (lit ...) [spec spec1 ...] ([non-term-id non-term-form ...] ...) desc ...)
@ -543,7 +545,7 @@
(define (annote-exporting-library e) (define (annote-exporting-library e)
(make-delayed-element (make-delayed-element
(lambda (render p ri) (lambda (render p ri)
(let ([from (resolve-get p ri '(exporting-libraries #f))]) (let ([from (resolve-get/tentative p ri '(exporting-libraries #f))])
(if (and from (if (and from
(pair? from)) (pair? from))
(list (make-hover-element (list (make-hover-element
@ -890,6 +892,12 @@
(define (*defstruct stx-id name fields field-contracts immutable? transparent? content-thunk) (define (*defstruct stx-id name fields field-contracts immutable? transparent? content-thunk)
(define spacer (hspace 1)) (define spacer (hspace 1))
(define to-flow (lambda (e) (make-flow (list (make-paragraph (list e)))))) (define to-flow (lambda (e) (make-flow (list (make-paragraph (list e))))))
(define (field-name f) (if (pair? (car f))
(caar f)
(car f)))
(define (field-view f) (if (pair? (car f))
(make-shaped-parens (car f) #\[)
(car f)))
(make-splice (make-splice
(cons (cons
(make-table (make-table
@ -914,13 +922,18 @@
(list 'make- name) (list 'make- name)
(append (append
(map (lambda (f) (map (lambda (f)
(list name '- (car f))) (list name '- (field-name f)))
fields) fields)
(if immutable? (if immutable?
null null
(map (lambda (f) (filter
(list 'set- name '- (car f) '!)) values
fields))))))]) (map (lambda (f)
(if (and (pair? (car f))
(memq '#:immutable (car f)))
#f
(list 'set- name '- (field-name f) '!)))
fields)))))))])
(if (pair? name) (if (pair? name)
(to-element (list just-name (to-element (list just-name
(make-just-context (cadr name) stx-id))) (make-just-context (cadr name) stx-id)))
@ -928,12 +941,18 @@
[short-width (apply + [short-width (apply +
(length fields) (length fields)
8 8
(map (lambda (s) (append
(string-length (symbol->string s))) (map (lambda (s)
(append (if (pair? name) (string-length (symbol->string s)))
name (append (if (pair? name)
(list name)) name
(map car fields))))]) (list name))
(map field-name fields)))
(map (lambda (f)
(if (pair? (car f))
(+ 3 2 (string-length (keyword->string (cadar f))))
0))
fields)))])
(if (and (short-width . < . max-proto-width) (if (and (short-width . < . max-proto-width)
(not immutable?) (not immutable?)
(not transparent?)) (not transparent?))
@ -942,7 +961,7 @@
(to-element (to-element
`(,(schemeparenfont "struct") `(,(schemeparenfont "struct")
,the-name ,the-name
,(map car fields))))) ,(map field-view fields)))))
(make-table (make-table
#f #f
(append (append
@ -958,8 +977,8 @@
(schemeparenfont "("))))) (schemeparenfont "(")))))
(to-flow (if (or (null? fields) (to-flow (if (or (null? fields)
(short-width . < . max-proto-width)) (short-width . < . max-proto-width))
(to-element (map car fields)) (to-element (map field-view fields))
(to-element (caar fields)))))) (to-element (field-view (car fields)))))))
(if (short-width . < . max-proto-width) (if (short-width . < . max-proto-width)
null null
(let loop ([fields fields]) (let loop ([fields fields])
@ -971,7 +990,7 @@
(to-flow spacer) (to-flow spacer)
(to-flow spacer) (to-flow spacer)
(to-flow (to-flow
(let ([e (to-element (car fld))]) (let ([e (to-element (field-view fld))])
(if (null? (cdr fields)) (if (null? (cdr fields))
(make-element (make-element
#f #f
@ -1033,7 +1052,7 @@
#f #f
(list (list
(list (to-flow (hspace 2)) (list (to-flow (hspace 2))
(to-flow (to-element (car v))) (to-flow (to-element (field-name v)))
(to-flow spacer) (to-flow spacer)
(to-flow ":") (to-flow ":")
(to-flow spacer) (to-flow spacer)
@ -1322,9 +1341,9 @@
;; ---------------------------------------- ;; ----------------------------------------
(provide defclass (provide defclass
define-class-doc defclass/title
definterface definterface
define-interface-doc definterface/title
defconstructor defconstructor
defconstructor/make defconstructor/make
defconstructor*/make defconstructor*/make
@ -1333,141 +1352,135 @@
defmethod* defmethod*
methspec methspec
methimpl methimpl
this-obj this-obj)
include-class-section
include-class)
(define-syntax-parameter current-class #f) (define-syntax-parameter current-class #f)
(define-struct decl (name super intfs mk-head body methods)) (define-struct decl (name super intfs mk-head body))
(define-struct constructor (def)) (define-struct constructor (def))
(define-struct meth (name mode desc def)) (define-struct meth (name mode desc def))
(define-struct spec (def)) (define-struct spec (def))
(define-struct impl (def)) (define-struct impl (def))
(define-for-syntax (class-id->class-doc-info-id id) (define-serializable-struct cls/intf (name-element super intfs methods))
(datum->syntax-object id
(string->symbol (format "class-doc-info:~a" (syntax-e id)))
id))
(define-syntax (define-class-doc-info stx) (define (make-inherited-table r d ri decl)
(syntax-case stx () (let* ([start (let ([key (register-scheme-definition (decl-name decl))])
[(_ id val) (list (cons key (lookup-cls/intf d ri key))))]
(with-syntax ([id (class-id->class-doc-info-id #'id)]) [supers (cdr
#'(begin (let loop ([supers start][accum null])
(provide id) (cond
(define id val)))])) [(null? supers) (reverse accum)]
[(memq (car supers) accum)
(define-syntax (class-doc-info stx) (loop (cdr supers) accum)]
(syntax-case* stx (object%) module-label-identifier=? [else
[(_ object%) #'#f] (let ([super (car supers)])
[(_ id) (class-id->class-doc-info-id #'id)])) (loop (append (map (lambda (i)
(cons i (lookup-cls/intf d ri i)))
(define (collect-inherited supers ht) (reverse (cls/intf-intfs (cdr super))))
(let* ([supers (let loop ([supers supers][accum null]) (let ([s (cls/intf-super (cdr super))])
(cond (if s
[(null? supers) (reverse accum)] (list (cons s (lookup-cls/intf d ri s)))
[(memq (car supers) accum) null))
(loop (cdr supers) accum)] (cdr supers))
[else (cons super accum)))])))]
(let ([super (car supers)]) [ht (let ([ht (make-hash-table)])
(loop (append (reverse (decl-intfs super)) (for-each (lambda (i)
(if (decl-super super) (when (meth? i)
(list (decl-super super)) (hash-table-put! ht (meth-name i) #t)))
null) (decl-body decl))
(cdr supers)) ht)]
(cons super accum)))]))]
[inh (apply [inh (apply
append append
(map (lambda (super) (map (lambda (super)
(let ([inh (filter (let ([inh (filter
values values
(hash-table-map (map
(decl-methods super) (lambda (k)
(lambda (k v) (if (hash-table-get ht k #f)
(let ([v (hash-table-get ht k)]) #f
(and (eq? (car v) (decl-name super)) (begin
(cons (symbol->string k) (hash-table-put! ht k #t)
(*method k (car v))))))))]) (cons (symbol->string k)
(**method k (car super))))))
(cls/intf-methods (cdr super))))])
(if (null? inh) (if (null? inh)
null null
(cons (cons
(make-element #f (list (make-element "inheritedlbl" '("from ")) (make-element #f (list (make-element "inheritedlbl" '("from "))
(to-element (decl-name super)))) (cls/intf-name-element (cdr super))))
(map cdr (sort inh (map cdr (sort inh
(lambda (a b) (lambda (a b)
(string<? (car a) (car b))))))))) (string<? (car a) (car b)))))))))
supers))]) supers))])
(if (null? inh) (if (null? inh)
null (make-auxiliary-table "inherited" null)
(list (make-auxiliary-table (make-auxiliary-table
"inherited" "inherited"
(map (lambda (i)
(list (make-flow (list (make-paragraph (list i))))))
(cons (make-element "inheritedlbl" '("Inherited methods:")) inh)))))))
(define (register-class name super intfs mk-head body)
(let ([ht (make-hash-table)])
(when super
(hash-table-for-each (decl-methods super)
(lambda (k v)
(hash-table-put! ht k v))))
(for-each (lambda (intf)
(hash-table-for-each (decl-methods intf)
(lambda (k v)
(hash-table-put! ht k v))))
intfs)
(for-each (lambda (i)
(when (meth? i)
(hash-table-put! ht (meth-name i) (cons name i))))
body)
(make-decl name super intfs mk-head
(append body
(collect-inherited (append
(if super (list super) null)
intfs)
ht))
ht)))
(define (*include-class-section decl)
(make-splice
(cons (section #:style 'hidden (to-element (decl-name decl)))
(map (lambda (i) (map (lambda (i)
(cond (list (make-flow (list (make-paragraph (list i))))))
[(constructor? i) ((constructor-def i))] (cons (make-element "inheritedlbl" '("Inherited methods:")) inh))))))
[(meth? i)
((meth-def i) (meth-desc i))] (define (make-decl-collect decl)
[else i])) (make-part-collect-decl
(append (make-collect-element
((decl-mk-head decl) #t) #f null
(decl-body decl)))))) (lambda (ci)
(let ([tag (register-scheme-definition (decl-name decl))])
(collect-put! ci
`(cls/intf ,tag)
(make-cls/intf
(make-element
"schemesymbol"
(list (make-link-element
"schemevaluelink"
(list (symbol->string (syntax-e (decl-name decl))))
tag)))
(and (decl-super decl)
(not (module-label-identifier=? #'object% (decl-super decl)))
(register-scheme-definition (decl-super decl)))
(map register-scheme-definition (decl-intfs decl))
(map (lambda (m)
(meth-name m))
(filter meth? (decl-body decl))))))))))
(define (build-body decl body)
(append
(map (lambda (i)
(cond
[(constructor? i) ((constructor-def i))]
[(meth? i)
((meth-def i) (meth-desc i))]
[else i]))
body)
(list
(make-delayed-flow-element
(lambda (r d ri)
(make-inherited-table r d ri decl))))))
(define (*include-class/title decl)
(make-splice
(list* (title #:style 'hidden (to-element (decl-name decl)))
(make-decl-collect decl)
(build-body decl
(append
((decl-mk-head decl) #t)
(decl-body decl))))))
(define (*include-class decl) (define (*include-class decl)
(make-splice (make-splice
(append (cons
((decl-mk-head decl) #f) (make-decl-collect decl)
(list (append
(make-blockquote ((decl-mk-head decl) #f)
"leftindent" (list
(flow-paragraphs (make-blockquote
(decode-flow "leftindent"
(map (lambda (i) (flow-paragraphs
(cond (decode-flow
[(constructor? i) ((constructor-def i))] (build-body decl (decl-body decl))))))))))
[(meth? i)
((meth-def i) (meth-desc i))]
[else i]))
(decl-body decl)))))))))
(define-syntax include-class-section (define (*class-doc stx-id super intfs whole-page?)
(syntax-rules ()
[(_ id) (*include-class-section (class-doc-info id))]))
(define-syntax include-class
(syntax-rules ()
[(_ id) (*include-class (class-doc-info id))]))
(define (*define-class-doc stx-id super intfs whole-page?)
(let ([spacer (hspace 1)]) (let ([spacer (hspace 1)])
(make-table (make-table
'boxed 'boxed
@ -1476,7 +1489,7 @@
(list (make-flow (list (make-flow
(list (list
(make-paragraph (make-paragraph
(list (let ([tag (register-scheme-definition stx-id #t)] (list (let ([tag (register-scheme-definition stx-id)]
[content (list (annote-exporting-library (to-element stx-id)))]) [content (list (annote-exporting-library (to-element stx-id)))])
(if tag (if tag
((if whole-page? ((if whole-page?
@ -1521,51 +1534,57 @@
(make-flow (list (make-paragraph (list (to-element i))))))) (make-flow (list (make-paragraph (list (to-element i)))))))
(cdr intfs))))))))))))) (cdr intfs)))))))))))))
(define-syntax define-class-doc (define-syntax *defclass
(syntax-rules () (syntax-rules ()
[(_ name super (intf ...) body ...) [(_ *include-class name super (intf ...) body ...)
(define-class-doc-info name (*include-class
(syntax-parameterize ([current-class (quote-syntax name)]) (syntax-parameterize ([current-class (quote-syntax name)])
(register-class (quote-syntax/loc name) (make-decl (quote-syntax/loc name)
(class-doc-info super) (quote-syntax/loc super)
(list (class-doc-info intf) ...) (list (quote-syntax/loc intf) ...)
(lambda (whole-page?) (lambda (whole-page?)
(list (list
(*define-class-doc (quote-syntax/loc name) (*class-doc (quote-syntax/loc name)
(quote-syntax super) (quote-syntax super)
(list (quote-syntax intf) ...) (list (quote-syntax intf) ...)
whole-page?))) whole-page?)))
(list body ...))))])) (list body ...))))]))
(define-syntax defclass (define-syntax defclass
(syntax-rules () (syntax-rules ()
[(_ name . rest) [(_ name super (intf ...) body ...)
(begin (*defclass *include-class name super (intf ...) body ...)]))
(define-class-doc name . rest)
(include-class name))]))
(define-syntax define-interface-doc (define-syntax defclass/title
(syntax-rules () (syntax-rules ()
[(_ name (intf ...) body ...) [(_ name super (intf ...) body ...)
(define-class-doc-info name (*defclass *include-class/title name super (intf ...) body ...)]))
(syntax-parameterize ([current-class (quote-syntax name)])
(register-class (quote-syntax/loc name)
#f
(list (class-doc-info intf) ...)
(lambda (whole-page?)
(list
(*define-class-doc (quote-syntax/loc name)
#f
(list (quote-syntax intf) ...)
whole-page?)))
(list body ...))))]))
(define-syntax *definterface
(syntax-rules ()
[(_ *include-class name (intf ...) body ...)
(*include-class
(syntax-parameterize ([current-class (quote-syntax name)])
(make-decl (quote-syntax/loc name)
#f
(list (quote-syntax/loc intf) ...)
(lambda (whole-page?)
(list
(*class-doc (quote-syntax/loc name)
#f
(list (quote-syntax intf) ...)
whole-page?)))
(list body ...))))]))
(define-syntax definterface (define-syntax definterface
(syntax-rules () (syntax-rules ()
[(_ name . rest) [(_ name (intf ...) body ...)
(begin (*definterface *include-class name (intf ...) body ...)]))
(define-interface-doc name . rest)
(include-class name))])) (define-syntax definterface/title
(syntax-rules ()
[(_ name (intf ...) body ...)
(*definterface *include-class/title name (intf ...) body ...)]))
(define-syntax (defconstructor*/* stx) (define-syntax (defconstructor*/* stx)
(syntax-case stx () (syntax-case stx ()
@ -1628,7 +1647,7 @@
[(override) "Overrides "] [(override) "Overrides "]
[(extend) "Extends "] [(extend) "Extends "]
[(augment) "Augments "]) [(augment) "Augments "])
(*xmethod/super (class-doc-info cname) 'name1) "."))] (*xmethod/super (quote-syntax/loc cname) 'name1) "."))]
[else [else
null])]) null])])
#'(make-meth 'name1 #'(make-meth 'name1
@ -1671,17 +1690,43 @@
(with-syntax ([cname (syntax-parameter-value #'current-class)]) (with-syntax ([cname (syntax-parameter-value #'current-class)])
#'(*this-obj 'cname))])) #'(*this-obj 'cname))]))
(define (*xmethod/super decl name) (define (*xmethod/super cname name)
(let ([super (ormap (lambda (decl) (let ([get
(and decl (lambda (d ri key)
(let ([m (hash-table-get (decl-methods decl) name #f)]) (let ([v (lookup-cls/intf d ri key)])
(and m (car m))))) (if v
(cons (decl-super decl) (cons (cls/intf-super v)
(decl-intfs decl)))]) (cls/intf-intfs v))
(make-element #f null)))])
(list (*method name super) (make-delayed-element
" in " (lambda (r d ri)
(to-element super))))) (let loop ([search (get d ri (register-scheme-definition cname))])
(cond
[(null? search)
(make-element #f "<method not found>")]
[(not (car search))
(loop (cdr search))]
[else
(let ([v (lookup-cls/intf d ri (car search))])
(if v
(if (member name (cls/intf-methods v))
(list
(make-element #f
(list (**method name (car search))
" in "
(cls/intf-name-element v))))
(loop (append (cdr search) (get d ri (car search)))))
(loop (cdr search))))])))
(lambda () (format "~a in ~a" (syntax-e cname) name))
(lambda () (format "~a in ~a" (syntax-e cname) name)))))
(define (lookup-cls/intf d ri name)
(let ([v (resolve-get d ri `(cls/intf ,name))])
(or v
(make-cls/intf "unknown"
#f
null
null))))
;; ---------------------------------------- ;; ----------------------------------------
) )

10
collects/scribble/scheme.ss
View File

@ -78,7 +78,7 @@
(lambda (renderer sec ri) (lambda (renderer sec ri)
(let* ([vtag `(def ,tag)] (let* ([vtag `(def ,tag)]
[stag `(form ,tag)] [stag `(form ,tag)]
[sd (resolve-get sec ri stag)]) [sd (resolve-get/tentative sec ri stag)])
(list (list
(cond (cond
[sd [sd
@ -541,11 +541,15 @@
(car b)) (car b))
(cadr b))))) (cadr b)))))
(define (register-scheme/invent stx warn-if-no-label?)
(or (register-scheme stx warn-if-no-label?)
(format ":UNKNOWN:~a" (syntax-e stx))))
(define (register-scheme-definition stx [warn-if-no-label? #f]) (define (register-scheme-definition stx [warn-if-no-label? #f])
`(def ,(register-scheme stx warn-if-no-label?))) `(def ,(register-scheme/invent stx warn-if-no-label?)))
(define (register-scheme-form-definition stx [warn-if-no-label? #f]) (define (register-scheme-form-definition stx [warn-if-no-label? #f])
`(form ,(register-scheme stx warn-if-no-label?))) `(form ,(register-scheme/invent stx warn-if-no-label?)))
(define syntax-ize-hook (make-parameter (lambda (v col) #f))) (define syntax-ize-hook (make-parameter (lambda (v col) #f)))

10
collects/scribble/struct.ss
View File

@ -38,6 +38,14 @@
(values v #t))])))) (values v #t))]))))
(define (resolve-get part ri key) (define (resolve-get part ri key)
(let-values ([(v ext?) (resolve-get/where part ri key)])
(when ext?
(hash-table-put! (resolve-info-undef ri)
(tag-key key ri)
#t))
v))
(define (resolve-get/tentative part ri key)
(let-values ([(v ext?) (resolve-get/where part ri key)]) (let-values ([(v ext?) (resolve-get/where part ri key)])
v)) v))
@ -47,7 +55,7 @@
part-collected-info part-collected-info
collect-put! collect-put!
resolve-get resolve-get
resolve-get/where) resolve-get/tentative)
;; ---------------------------------------- ;; ----------------------------------------

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

@ -167,9 +167,13 @@ in a form definition.}
@; ------------------------------------------------------------------------ @; ------------------------------------------------------------------------
@section{Definition Reference} @section{Definition Reference}
@defform[(defproc (id arg-spec ...) @defform/subs[(defproc (id arg-spec ...)
result-contract-expr-datum result-contract-expr-datum
pre-flow ...)]{ pre-flow ...)
([arg-spec (arg-id contract-expr-datum)
(arg-id contract-expr-datum default-expr)
(keyword arg-id contract-expr-datum)
(keyword arg-id contract-expr-datum default-expr)])]{
Produces a sequence of flow elements (encaptured in a @scheme[splice]) Produces a sequence of flow elements (encaptured in a @scheme[splice])
to document a procedure named @scheme[id]. The @scheme[id] is indexed, to document a procedure named @scheme[id]. The @scheme[id] is indexed,
@ -368,56 +372,73 @@ at once, aligned around the @litchar{=} and @litchar{|}.}
@; ------------------------------------------------------------------------ @; ------------------------------------------------------------------------
@section{Classes and Interfaces} @section{Classes and Interfaces}
@defform[(define-class-doc id super-id (intf-id ...) pre-flow ...)]{ @defform[(defclass id super-id (intf-id ...) pre-flow ...)]{
Binds @schemeidfont{class-doc-info:}@scheme[id] to documentation for Creates documentation for a class @scheme[id] that is a subclass of
the class @scheme[id]. If @scheme[super-id] is not @scheme[object%], @scheme[super-id] and implements each interface @scheme[intf-id]. Each
then @schemeidfont{class-doc-info:}@scheme[super-id] must be bound to @scheme[super-id] (except @scheme[object%]) and @scheme[intf-id] must
documentation for the superclass (so that links can be created to be documented somewhere via @scheme[defclass] or @scheme[definterface].
inherited methods, etc.). Similarly,
@schemeidfont{class-doc-info:}@scheme[intf-id] must be bound to
documentation for interfaces implemented by the class. At the same
time, @scheme[id], @scheme[super-id], and the @scheme[int-id]s must
have for-label bindings that are used for hyperlinks in the usual way.
The decoding of the @scheme[pre-flow] sequence should start with The decoding of the @scheme[pre-flow] sequence should start with
general documentation about the class, followed by constructor general documentation about the class, followed by constructor
definition (see @scheme[defconstructor]), and then field and method definition (see @scheme[defconstructor]), and then field and method
definitions (see @scheme[defmethod]). definitions (see @scheme[defmethod]). In rendered form, the
constructor and method specification are indented to visually group
them under the class definition.}
A @scheme[define-class-doc] form is a Scheme-level definition. It does @defform[(defclass/title id super-id (intf-id ...) pre-flow ...)]{
not produce documentation directly. Instead, @scheme[(include-class
id)] or @scheme[(include-class-section id)] should be used later to
produce the documentation.}
@defform[(include-class id)]{ Like @scheme[defclass], also includes a @scheme[title] declaration
with the style @scheme['hidden]. In addition, the constructor and
methods are not left-indented.
Generates inline documentation based on the information bound to This form is normally used to create a section to be rendered on its
@schemeidfont{class-doc-info:}@scheme[id]. Constructor and method own HTML. The @scheme['hidden] style is used because the definition
specification are indented to visually group them under the class box serves as a title.}
definition.}
@defform[(include-class-section id)]{ @defform[(definterface id (intf-id ...) pre-flow ...)]{
Generates documentation based on the information bound to Like @scheme[defclass], but for an interfaces. Naturally,
@schemeidfont{class-doc-info:}@scheme[id] as a new section. The @scheme[pre-flow] should not generate a constructor declaration.}
@scheme[id] is used as the section title, but the title is not
rendered in HTML output, as the definition box serves as a title. With
the expectation that the section will have its own page, constructor
and method specifications are not indented (unlike the result of
@scheme[include-class]).}
@defform[(defclass id super-id (intf-id ...) pre-flow ...)]{ @defform[(definterface/title id (intf-id ...) pre-flow ...)]{
Combines @scheme[define-class-doc] and @scheme[include-class].} Like @scheme[definterface], but for single-page rendering as in
@scheme[defclass/title].}
@defform[(defconstructor)]{ @defform/subs[(defconstructor (arg-spec ...) pre-flow ...)
([arg-spec (arg-id contract-expr-datum)
(arg-id contract-expr-datum default-expr)])]{
TBD.} Like @scheme[defproc], but for a constructor declaration in the body
of @scheme[defclass], so no return contract is specified. Also, the
@scheme[new]-style keyword for each @scheme[arg-spec] is implicit from
the @scheme[arg-id].}
@defform[(defmethod)]{ @defform[(defconstructor/make (arg-spec ...) pre-flow ...)]{
TBD.} Like @scheme[defconstructor], but specifying by-position
initialization arguments (for use with @scheme[make-object]) instead
of by-name arguments (for use with @scheme[new]).}
@defform[(defconstructor*/make [(arg-spec ...) ...] pre-flow ...)]{
Like @scheme[defconstructor/make], but with multiple constructor
patterns analogous @scheme[defproc*].}
@defform[(defmethod (id arg-spec ...)
result-contract-expr-datum
pre-flow ...)]{
Like @scheme[defproc], but for a method within a @scheme[defclass] or
@scheme[definterface] body.}
@defform[(defmethod* ([(id arg-spec ...)
result-contract-expr-datum] ...)
pre-flow ...)]{
Like @scheme[defproc*], but for a method within a @scheme[defclass] or
@scheme[definterface] body.}
@; ------------------------------------------------------------------------ @; ------------------------------------------------------------------------
@section{Various String Forms} @section{Various String Forms}