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

adjust `racket/generic' documentation style

Browse Source
This commit is contained in:
Matthew Flatt 2012-06-03 02:57:39 +08:00
parent 232188e736
commit 900b66332c
1 changed files with 41 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
collects/scribblings/reference/generic.scrbl
View File

@ -15,57 +15,62 @@ using a @racket[define-generics] form. Method implementations for
a structure type are defined using the @racket[#:methods] keyword a structure type are defined using the @racket[#:methods] keyword
(see @secref["define-struct"]). (see @secref["define-struct"]).
@defform/subs[(define-generics name [#:defined-table defined-table] @defform/subs[(define-generics id [#:defined-table defined-table-id]
[method . kw-formals*] [method-id . kw-formals*]
...) ...)
([kw-formals* (arg* ...) ([kw-formals* (arg* ...)
(arg* ...+ . rest-id) (arg* ...+ . rest-id)
rest-id] rest-id]
[arg* id [arg* arg-id
[id] [arg-id]
(code:line keyword id) (code:line keyword arg-id)
(code:line keyword [id])]) (code:line keyword [arg-id])])]{
#:contracts
([name identifier?]
[defined-table identifier?]
[method identifier?])]{
Defines @racket[gen:name] as a transformer binding for the static Defines
information about a new generic interface.
Defines @racket[name?] as a predicate identifying instances of structure @itemlist[
types that implement this generic group.
Defines each @racket[method] as a generic procedure that calls the @item{@racketidfont{gen:}@racket[id] as a transformer binding for
corresponding method on values where @racket[name?] is true. Each method the static information about a new generic interface;}
must have a required by-position argument that is
@racket[free-identifier=?] to @racket[name]. This argument is used in
the generic definition to locate the specialization.
The optional @racket[defined-table] argument should be an identifier. @item{@racket[id]@racketidfont{?} as a predicate identifying
@racket[define-generics] will bind it to a procedure that takes an instance of instances of structure types that implement this generic group; and}
the generics and returns an immutable hash-table that maps symbols
corresponding to method names to booleans representing whether or not that
method is implemented by that instance. The intended use case for this table is
to allow higher-level APIs to adapt their behavior depending on method
availability.
} @item{each @racket[method-id] as a generic procedure that calls the
corresponding method on values where
@racket[id]@racketidfont{?} is true.}
@defform[(define/generic local-name method-name) ]
Each @racket[method-id]'s @racket[kw-formals*] must include a required
by-position argument that is @racket[free-identifier=?] to
@racket[id]. That argument is used in the generic definition to
locate the specialization.
When @racket[defined-table-id] is provided, it is defined as a
procedure that takes an instance of the generics and returns an
immutable @tech{hash table} that maps symbols corresponding to method
names to booleans representing whether or not that method is
implemented by the instance. This table is intended for use by
higher-level APIs to adapt their behavior depending on method
availability.}
@defform[(define/generic local-id method-id)
#:contracts #:contracts
([local-name identifier?] ([local-id identifier?]
[method-name identifier?])]{ [method-id identifier?])]{
When used inside the method definitions associated with the When used inside the method definitions associated with the
@racket[#:methods] keyword, binds @racket[local-name] to @racket[#:methods] keyword, binds @racket[local-id] to the generic for
the generic for @racket[method-name]. This is useful for method @racket[method-id]. This form is useful for method specializations to
specializations to use the generic methods on other values. use generic methods (as opposed to the local specialization) on other
values.
Syntactically an error when used outside the definitions associated Using the @racket[define/generic] form outside a @racket[#:methods]
with @racket[#:methods]. specification in @racket[struct] (or @racket[define-struct]) is an
syntax error.}
}
@; Examples @; Examples
@(require scribble/eval) @(require scribble/eval)