4.2.4 Documenting Classes and Interfaces

► |  | Scribble: The Racket Documentation Tool

1 | Getting Started
2 | @ Syntax
3 | High-Level Scribble API
4 | Scribbling Documentation
5 | Literate Programming
6 | Low-Level Scribble API
7 | Running scribble
| Index

► | 4 | Scribbling Documentation

4.1 | Getting Started with Documentation
4.2 | Manual Forms
4.3 | Racket
4.4 | Evaluation and Examples
4.5 | In-Source Documentation
4.6 | BNF Grammars
4.7 | Compatibility Libraries

▼ | 4.2 | Manual Forms

4.2.1 | Typesetting Code
4.2.2 | Documenting Modules
4.2.3 | Documenting Forms, Functions, Structure Types, and Values
4.2.4 | Documenting Classes and Interfaces
4.2.5 | Documenting Signatures
4.2.6 | Various String Forms
4.2.7 | Links
4.2.8 | Indexing
4.2.9 | Bibliography
4.2.10 | Version History
4.2.11 | Miscellaneous
4.2.12 | Index-Entry Descriptions
4.2.13 | Manual Rendering Style

On this page:

defclass
defclass/ title
definterface
definterface/ title
defmixin
defmixin/ title
defconstructor
defconstructor/ make
defconstructor*/ make
defconstructor/ auto-super
defmethod
defmethod*
method
xmethod
this-obj

Racket
top contents ← prev up next →

#### 4.2.4 Documenting Classes and Interfaces🔗ℹ

> syntax (defclass maybe-link id super (intf ...) pre-flow ...)
> maybe-link |  | = |  |
> |  | | |  | #:link-target? link-target?-expr
> super |  | = |  | super-id
> |  | | |  | (mixin-id super)
> intf |  | = |  | intf-id
> |  | | |  | [#:no-inherit intf-id]

Creates documentation for a class id that is a subclass of super and implements each interface intf-id. Each identifier in super (except object%) and intf-id must be documented somewhere via defclass or definterface.

The decoding of the pre-flow sequence should start with general documentation about the class, followed by constructor definition (see defconstructor), and then field and method definitions (see defmethod). In rendered form, the constructor and method specification are indented to visually group them under the class definition.

When an intf-id is specified with #:no-inherit, then the set of inherited methods for id does not include methods from intf-id. Omitting methods in this way can avoid a documentation dependency when no direct reference to a method of intf-id is needed.

Changed in version 1.42 of package scribble-lib: Added #:no-inherit for intf.

> syntax (defclass/title maybe-link id super (intf ...) pre-flow ...)

Like defclass, also includes a title declaration with the style 'hidden. In addition, the constructor and methods are not left-indented.

This form is normally used to create a section to be rendered on its own HTML. The 'hidden style is used because the definition box serves as a title.

Changed in version 1.42 of package scribble-lib: Added #:no-inherit for intf.

> syntax (definterface id (intf ...) pre-flow ...)

Like defclass, but for an interfaces. Naturally, pre-flow should not generate a constructor declaration.

Changed in version 1.42 of package scribble-lib: Added #:no-inherit for intf.

> syntax (definterface/title id (intf ...) pre-flow ...)

Like definterface, but for single-page rendering as in defclass/title.

Changed in version 1.42 of package scribble-lib: Added #:no-inherit for intf.

> syntax (defmixin id (domain-id ...) (range-id ...) pre-flow ...)

Like defclass, but for a mixin. Any number of domain-id classes and interfaces are specified for the mixin’s input requires, and any number of result classes and (more likely) interfaces are specified for the range-id. The domain-ids supply inherited methods, and they can include interfaces annotated with #:no-inherit.

Changed in version 1.42 of package scribble-lib: Added #:no-inherit support for domain-id.

> syntax (defmixin/title id (domain-id ...) (range-id ...) pre-flow ...)

Like defmixin, but for single-page rendering as in defclass/title.

> syntax (defconstructor (arg-spec ...) pre-flow ...)
> arg-spec |  | = |  | (arg-id contract-expr-datum)
> |  | | |  | (arg-id contract-expr-datum default-expr)

Like defproc, but for a constructor declaration in the body of defclass, so no return contract is specified. Also, the new-style keyword for each arg-spec is implicit from the arg-id.

> syntax (defconstructor/make (arg-spec ...) pre-flow ...)

Like defconstructor, but specifying by-position initialization arguments (for use with make-object) instead of by-name arguments (for use with new).

> syntax (defconstructor*/make [(arg-spec ...) ...] pre-flow ...)

Like defconstructor/make, but with multiple constructor patterns analogous defproc*.

> syntax (defconstructor/auto-super [(arg-spec ...) ...] pre-flow ...)

Like defconstructor, but the constructor is annotated to indicate that additional initialization arguments are accepted and propagated to the superclass.

> > syntax
> > (defmethod maybe-mode maybe-link (id arg-spec ...)
> > result-contract-expr-datum
> > pre-flow ...)
> maybe-link |  | = |  |
> |  | | |  | #:link-target? link-target?-expr
> maybe-mode |  | = |  |
> |  | | |  | #:mode public
> |  | | |  | #:mode public-final
> |  | | |  | #:mode override
> |  | | |  | #:mode override-final
> |  | | |  | #:mode augment
> |  | | |  | #:mode augment-final
> |  | | |  | #:mode extend
> |  | | |  | #:mode extend-final
> |  | | |  | #:mode pubment

Like defproc, but for a method within a defclass or definterface body.

The maybe-mode specifies whether the method overrides a method from a superclass, and so on. (For these purposes, use #:mode override when refining a method of an implemented interface.) The extend mode is like override, but the description of the method should describe only extensions to the superclass implementation. When maybe-mode is not supplied, it defaults to public.

Changed in version 1.35 of package scribble-lib: Added a check against invalid maybe-mode.

> > syntax
> > (defmethod* maybe-mode maybe-link
> > ([(id arg-spec ...)
> > result-contract-expr-datum] ...)
> > pre-flow ...)

Like defproc*, but for a method within a defclass or definterface body. The maybe-mode specification is as in defmethod.

> syntax (method class/intf-id method-id)

Creates a hyperlink to the method named by method-id in the class or interface named by class/intf-id. The hyperlink names the method, only; see also xmethod.

For-label binding information is used with class/intf-id, but not method-id.

> syntax (xmethod class/intf-id method-id)

Like method, but the hyperlink shows both the method name and the containing class/interface.

> syntax (this-obj)

Within a defmethod or similar form, typesets as a meta-variable that stands for the target of the method call. Use (this-obj) to be more precise than prose such as “this method’s object.”
top contents ← prev up next →