Dylan Domain Reference¶

This document describes the “dylan” Sphinx domain which contains directives and roles for documenting Dylan source code.

Note that while directives are shown here in their full form, :dylan:foo:`...`, most Dylan documentation sets “dylan” as the default domain in conf.py with

primary_domain = 'dylan'

which makes it possible to simply write :foo:`...` instead.

Dylan Reference Manual links¶

Roles¶

`:dylan:drm:`¶

Reference to a page or exported name in the Dylan Reference Manual.

Syntax 1:

:dylan:drm:`LINKNAME`

Syntax 2:

:dylan:drm:`DISPLAYED TEXT <LINKNAME>`

LINKNAME is an exported name or the last part of the URL of a page or section. Exported names are converted into partial URLs per the file configured by dylan_drm_index. The partial URL is appended to the base URL configured by the dylan_drm_url.

Configurables¶

`dylan_drm_url`¶

The base URL of the Dylan Reference Manual. Defaults to the base URL of the copy at http://opendylan.org.

`dylan_drm_index`¶

A file listing Dylan names and the corresponding Dylan Reference Manual partial URLs. Each line is a correspondence. The first word is the Dylan name, followed by whitespace, then the remainder is the partial URL. Defaults to partial URLs corresponding to the copy of the Dylan Reference Manual at http://opendylan.org.

Library, module, and binding documentation¶

The Dylan domain generates an API index in a file called dylan-apiindex.html. Unfortunately, you have to link to it by filename, e.g.

* `API Index <dylan-apiindex.html>`_

Directives with content¶

`dylan:library::`¶

A library. You can document the modules exported by the library inside or after this directive, or elsewhere via dylan:current-library::.

Syntax:

.. dylan:library:: NAME

Options:

None

Doc Fields:

:summary:, :discussion:, :seealso:

References:

:dylan:lib:

`dylan:module::`¶

A module. You can document the names exported by the module inside or after this directive, or elsewhere via dylan:current-module::.

Syntax:

.. dylan:module:: NAME

Options:

:library:

Doc Fields:

:summary:, :discussion:, :seealso:

References:

:dylan:mod:

`dylan:class::`¶

A class.

Syntax:

.. dylan:class:: NAME

Options:

:open:, :sealed:, :primary:, :free:, :abstract:, :concrete:, :instantiable:, :uninstantiable:, :adjectives:, :library:, :module:

Doc Fields:

:supers:, :keyword:, :slot:, :summary:, :discussion:, :conditions:, :operations:, :example:, :seealso:

References:

:dylan:class:

Example:
.. class:: <vector>
   :open:

   :supers: `<array>`:class
   :keyword size:  An instance of `<integer>`:class: specifying the size
                   of the vector. The default value is ``0``.
   :keyword required fill:
       An instance of `<object>`:class: specifying the initial value for
       each element of the vector. The default value is ``#f``.

`dylan:generic-function::`¶

A generic function.

Syntax:

.. dylan:generic-function:: NAME

Options:

:open:, :sealed:, :adjectives:, :library:, :module:

Doc Fields:

:param:, :value: (1), :signature:, :summary:, :discussion:, :conditions:, :example:, :seealso:

References:

:dylan:gf:

Example:
.. generic-function:: member?
   :sealed:

   :param value:        An instance of `<object>`:class:.
   :param collection:   An instance of `<collection>`:class:.
   :param #key test:    An instance of `<function>`:class:. The default is
                        `==`:gf:.
   :value bool:         An instance of `<boolean>`:class:.

`dylan:method::`¶

A method of a generic function.

Syntax:

.. dylan:method:: NAME

Options:

:specializer:, :sealed:, :adjectives:, :library:, :module:

Doc Fields:

:param:, :value: (1), :signature:, :summary:, :discussion:, :conditions:, :example:, :seealso:

References:

:dylan:meth:

References to a method must be disambiguated by enclosing SPECIALIZER in parentheses, as shown by the reference to type-for-copy in the following example. The specializer is author-defined and does not necessarily have to reflect all the parameters of the method.

Example:
.. method:: copy-sequence
   :specializer: <range>

   :param source:       An instance of `<range>`:class:.
   :param #key start:   An instance of `<integer>`:class. The default is
                        ``0``.
   :param #key end:     An instance of `<integer>`:class. The default is
                        the size of *source*.
   :value new-range:    A freshly allocated instance of `<range>`:class:.

   *new-range* will be a `<range>`:class: even though the return value of
   `type-for-copy(<range>)`:meth: is a `<list>`:class:.

`dylan:function::`¶

A function that does not belong to a generic function.

Syntax:

.. dylan:function:: NAME

Options:

:adjectives:, :library:, :module:

Doc Fields:

:param:, :value: (1), :signature:, :summary:, :discussion:, :conditions:, :example:, :seealso:

References:

:dylan:func:

`dylan:primitive::`¶

A primitive operation.

Syntax:

.. dylan:primitive:: NAME`

Options:

:adjectives:, :library:, :module:

Doc Fields:

:param:, :value: (1), :signature:, :summary:, :discussion:, :conditions:, :example:, :seealso:

References:

:dylan:prim:

`dylan:constant::`¶

A constant.

Syntax:

.. dylan:constant:: NAME

Options:

:adjectives:, :library:, :module:

Doc Fields:

:type:, :value: (2), :summary:, :discussion:, :example:, :seealso:

References:

:dylan:const:

`dylan:type::`¶

A type.

Syntax:

.. dylan:type:: NAME

Options:

:adjectives:, :library:, :module:

Doc Fields:

:type:, :value: (2), :summary:, :discussion:, :example:, :supertypes:, :operations:, :equivalent:, :seealso:

References:

:dylan:type:

`dylan:variable::`¶

A variable.

Syntax:

.. dylan:variable:: NAME

Options:

:adjectives:, :library:, :module:

Doc Fields:

:type:, :value: (2), :summary:, :discussion:, :example:, :seealso:

References:

:dylan:var:

`dylan:macro::`¶

A macro.

Syntax:

.. dylan:macro:: NAME

Options:

:statement:, :function:, :defining:, :macro-type:, :adjectives:, :library:, :module:

Doc Fields:

:param:, :value: (1), :macrocall:, :summary:, :discussion:, :example:, :seealso:

References:

:dylan:macro:

Directives without content¶

`dylan:current-library::`¶

Sets the library currently being documented when the actual library documentation is elsewhere. You can document the modules exported by the library after this directive.

Syntax:

.. dylan:current-library:: LIBRARY

Options:

None

`dylan:current-module::`¶

Sets the module currently being documented when the actual module documentation is elsewhere. You can document the names exported by the module after this directive.

Syntax:

.. dylan:current-module:: MODULE

Options:

None

Directive doc fields¶

Doc fields appear in the directive’s content. Doc fields must be separated from the directive and any directive options by a blank line.

`:summary:`¶

A brief summary of a Dylan language element.

Syntax:

:summary: DISCUSSION

Synonyms:

None

`:discussion:`¶

A discussion of a Dylan language element.

Syntax:

:discussion: DISCUSSION

Synonyms:

:description:

`:seealso:`¶

A set of items that are related to the current element.

Syntax:

:seealso: OTHER ELEMENTS

Synonyms:

None

`:example:`¶

An example of the use of a binding. This doc field may appear multiple times.

Syntax:

:example: EXAMPLE

Synonyms:

None

`:supers:`¶

A superclass of a class. This doc field may appear multiple times.

Syntax:

:supers: DESCRIPTION

Synonyms:

:superclasses:, :super:, :superclass:

`:keyword:`¶

An init-keyword of a class. This doc field may appear multiple times.

Syntax 1:

:keyword NAME: DESCRIPTION

Syntax 2:

:keyword required NAME: DESCRIPTION

Synonyms:

:init-keyword:

See dylan:class:: for an example.

`:slot:`¶

A slot of a class. This doc field may appear multiple times.

Syntax:

:slot NAME: DESCRIPTION

Synonyms:

:getter:

`:operations:`¶

A list of methods or functions applicable to a class.

Syntax:

:operations: LIST

Synonyms:

:methods:, :functions:

`:param:`¶

A parameter of a generic function or method. This doc field may appear multiple times.

Syntax 1:

:param NAME: DESCRIPTION

Syntax 2:

:param #key NAME: DESCRIPTION

Syntax 3:

:param #rest NAME: DESCRIPTION

Synonyms:

:parameter:

See dylan:generic-function:: and dylan:method:: for examples.

`:value:` (1)¶

A return value of a generic function or method. This doc field may appear multiple times.

Syntax 1:

:value NAME: DESCRIPTION

Syntax 2:

:value #rest NAME: DESCRIPTION

Synonyms:

:return:, :retval:, :val:

See dylan:generic-function:: and dylan:method:: for examples.

`:type:`¶

The type of a variable or constant.

Syntax:

:type: EXPRESSION

Synonyms:

None

`:value:` (2)¶

The initial value of a variable or constant.

Syntax:

:value: EXPRESSION

Synonyms:

:val:

`:signature:`¶

The signature of a function.

Syntax:: :signature: TEXT
Synonyms:: :sig:

Example:

.. function:: error

   :signature: ``error`` *condition* => *will never return*
   :signature:
      ``error`` *string* ``#rest`` *arguments* => *will never return*

`:macrocall:`¶

The syntax of a macro call.

Syntax:

:macrocall: BODY

Synonyms:

:call:, :syntax:

Example:
.. macro:: variable-definer

   :macrocall:
      .. parsed-literal::
         define { `adjective }* variable `variables` = `init`

`:conditions:`¶

A discussion of conditions signaled by a function or by a class’s make or initialize.

Syntax:

:conditions: DISCUSSION

Synonyms:

:exceptions:, :signals:, :throws:, :condition:, :exception:

`:supertypes:`¶

A supertype of a type. This doc field may appear multiple times.

Syntax:

:supertypes: DESCRIPTION

Synonyms:

:supertype:, :super:, :supers:

`:equivalent:`¶

The equivalent of a type.

Syntax:

:equivalent: DESCRIPTION

Directive options¶

Directive options appear immediately after the directive with no intervening blank lines.

`:library:`¶

Sets the current library, also affecting documentation following the directive. Mostly for automatically-generated documentation; hand-written documentation can use dylan:current-library::.

Syntax:

:library: NAME

`:module:`¶

Sets the current module, also affecting documentation following the directive. Mostly for automatically-generated documentation; hand-written documentation can use dylan:current-module::.

Syntax:

:module: NAME

`:specializer:`¶

A way to distinguish one method from another – generally a list of the types of its required parameters. It cannot contain parentheses. This option is required in dylan:method:: directives.

Syntax:

:specializer: EXPRESSION, EXPRESSION, ...

See dylan:generic-function:: and dylan:method:: for examples.

`:open:`¶

Indicates an open class or generic function. Synonymous with :adjectives: open.

Syntax:

:open:

`:primary:`¶

Indicates a primary class. Synonymous with :adjectives: primary.

Syntax:

:primary:

`:free:`¶

Indicates a free class. Synonymous with :adjectives: free.

Syntax:

:free:

`:abstract:`¶

Indicates an abstract class. Synonymous with :adjectives: abstract.

Syntax:

:abstract:

`:concrete:`¶

Indicates a concrete class. Synonymous with :adjectives: concrete.

Syntax:

:concrete:

`:sealed:`¶

Indicates a sealed generic function, method, or class. Synonymous with :adjectives: sealed.

Syntax:

:sealed:

`:instantiable:`¶

Indicates an instantiable class. Synonymous with :adjectives: instantiable.

Syntax:

:instantiable:

`:uninstantiable:`¶

Indicates an uninstantiable class. Synonymous with :adjectives: uninstantiable.

Syntax:

:uninstantiable:

`:adjectives:`¶

Adjectives to a binding. You may use this to display implementation-specific adjectives.

Syntax:

:adjectives: ADJECTIVES

`:statement:`¶

Indicates a statement macro. Synonymous with :macro-type: statement.

Syntax:

:statement:

`:function:`¶

Indicates a function macro. Synonymous with :macro-type: function.

Syntax:

:function:

`:defining:`¶

Indicates a defining macro. Synonymous with :macro-type: defining.

Syntax:

:defining:

`:macro-type:`¶

Describes the type of a macro, in a general sense. Free-form.

Syntax:

:macro-type: TYPE

Roles¶

All cross-referencing roles except :dylan:meth: have the same syntax. This syntax is similar to the syntax of cross-referencing roles for other languages, but if you use the ! or ~ marks, you must enclose the target in < >, and the ~ mark does not have any effect.

Syntax 1:

:dylan:role:`LIBRARY:MODULE:NAME`

Syntax 2:

:dylan:role:`TEXT <LIBRARY:MODULE:NAME>`

Syntax 3:

:dylan:role:`MARK <LIBRARY:MODULE:NAME>`

Syntax 4:

:dylan:role:`MARK TEXT <LIBRARY:MODULE:NAME>`

You may omit LIBRARY or MODULE to use the current library or module or link to a uniquely-named binding or module.

MARK may be ! to avoid making a hyperlink, or ~ which does not have an effect at the moment.

Examples:
.. current-library:  io
.. current-module:   streams

Be sure to call `~ <dylan:dylan:copy-sequence>`:gf: to avoid
unintentionally changing the values of the sequence.

See `the <stream> class <<stream>>`:class: for more information.

`:dylan:lib:`¶

Creates a cross-reference to a dylan:library:: directive.

`:dylan:mod:`¶

Creates a cross-reference to a dylan:module:: directive.

`:dylan:class:`¶

Creates a cross-reference to a dylan:class:: directive.

`:dylan:gf:`¶

Creates a cross-reference to a dylan:generic-function:: directive.

`:dylan:meth:`¶

Creates a cross-reference to a dylan:method:: directive.

The syntax is similar to other roles.

Syntax 1:

:dylan:meth:`LIBRARY:MODULE:NAME(SPECIALIZER)`

Syntax 2:

:dylan:meth:`TEXT <LIBRARY:MODULE:NAME(SPECIALIZER)>`

Syntax 3:

:dylan:meth:`MARK <LIBRARY:MODULE:NAME(SPECIALIZER)>`

Syntax 4:

:dylan:meth:`MARK TEXT <LIBRARY:MODULE:NAME(SPECIALIZER)>`

The SPECIALIZER component matches a method directive’s :specializer: option. It cannot contain nested parentheses.

You may omit LIBRARY or MODULE to use the current library or module or link to a uniquely-named binding or module.

MARK may be ! to avoid making a hyperlink, or ~ which does not have an effect at the moment.

`:dylan:func:`¶

Creates a cross-reference to a dylan:function:: directive.

`:dylan:prim:`¶

Creates a cross-reference to a dylan:primitive:: directive.

`:dylan:const:`¶

Creates a cross-reference to a dylan:constant:: directive.

`:dylan:var:`¶

Creates a cross-reference to a dylan:variable:: directive.

`:dylan:type:`¶

Creates a cross-reference to a dylan:type:: directive.

`:dylan:macro:`¶

Creates a cross-reference to a dylan:macro:: directive.

Dylan Domain Reference¶

Dylan Reference Manual links¶

Roles¶

:dylan:drm:¶

Configurables¶

dylan_drm_url¶

dylan_drm_index¶

Library, module, and binding documentation¶

Directives with content¶

dylan:library::¶

dylan:module::¶

dylan:class::¶

dylan:generic-function::¶

dylan:method::¶

dylan:function::¶

dylan:primitive::¶

dylan:constant::¶

dylan:type::¶

dylan:variable::¶

dylan:macro::¶

Directives without content¶

dylan:current-library::¶

dylan:current-module::¶

Directive doc fields¶

:summary:¶

:discussion:¶

:seealso:¶

:example:¶

:supers:¶

:keyword:¶

:slot:¶

:operations:¶

:param:¶

:value: (1)¶

:type:¶

:value: (2)¶

:signature:¶

:macrocall:¶

:conditions:¶

:supertypes:¶

:equivalent:¶

Directive options¶

:library:¶

:module:¶

:specializer:¶

:open:¶

:primary:¶

:free:¶

:abstract:¶

:concrete:¶

:sealed:¶

:instantiable:¶

:uninstantiable:¶

:adjectives:¶

:statement:¶

:function:¶

:defining:¶

:macro-type:¶

Roles¶

:dylan:lib:¶

:dylan:mod:¶

:dylan:class:¶

:dylan:gf:¶

:dylan:meth:¶

:dylan:func:¶

:dylan:prim:¶

:dylan:const:¶

:dylan:var:¶

:dylan:type:¶

:dylan:macro:¶

`:dylan:drm:`¶

`dylan_drm_url`¶

`dylan_drm_index`¶

`dylan:library::`¶

`dylan:module::`¶

`dylan:class::`¶

`dylan:generic-function::`¶

`dylan:method::`¶

`dylan:function::`¶

`dylan:primitive::`¶

`dylan:constant::`¶

`dylan:type::`¶

`dylan:variable::`¶

`dylan:macro::`¶

`dylan:current-library::`¶

`dylan:current-module::`¶

`:summary:`¶

`:discussion:`¶

`:seealso:`¶

`:example:`¶

`:supers:`¶

`:keyword:`¶

`:slot:`¶

`:operations:`¶

`:param:`¶

`:value:` (1)¶

`:type:`¶

`:value:` (2)¶

`:signature:`¶

`:macrocall:`¶

`:conditions:`¶

`:supertypes:`¶

`:equivalent:`¶

`:library:`¶

`:module:`¶

`:specializer:`¶

`:open:`¶

`:primary:`¶

`:free:`¶

`:abstract:`¶

`:concrete:`¶

`:sealed:`¶

`:instantiable:`¶

`:uninstantiable:`¶

`:adjectives:`¶

`:statement:`¶

`:function:`¶

`:defining:`¶

`:macro-type:`¶

`:dylan:lib:`¶

`:dylan:mod:`¶

`:dylan:class:`¶

`:dylan:gf:`¶

`:dylan:meth:`¶

`:dylan:func:`¶

`:dylan:prim:`¶

`:dylan:const:`¶

`:dylan:var:`¶

`:dylan:type:`¶

`:dylan:macro:`¶