Generics

Generics will by default produce a list of methods that specialize them. Setf functions or methods will also be printed.

.. cl:generic:: symbol-name

The :cl:generic: directive emits the documentation for a generic function and its specializers:

.. cl:generic:: example-generic

Code

(defgeneric example-generic (arg1 arg2 &optional arg3)
  (:documentation "A test generic function."))

Output

Generic (example-generic arg1 arg2 &optional arg3)

(example-generic (arg1 EXAMPLE-CLASS) (arg2 (eql :TEST)) &OPTIONAL ARG3)

(example-generic (arg1 EXAMPLE-CLASS) (arg2 (eql :TEST1)) &OPTIONAL ARG3)

(example-generic (arg1 EXAMPLE-CLASS) (arg2 (eql :TEST2)) &OPTIONAL ARG3)

(example-generic (arg1 EXAMPLE-CLASS) (arg2 T) &OPTIONAL ARG3)

(setf (example-generic (arg1 EXAMPLE-CLASS) (arg2 (eql :TEST))) (new-value T))

(setf (example-generic (arg1 EXAMPLE-CLASS) (arg2 T)) (new-value EXAMPLE-CLASS))

A test generic function.

Disable listing specializers

Generics will also list other specializing methods by default this behaviour can be disabled by passing the ::nospecializers:: option:

.. cl:generic:: example-generic
   :nospecializers:

The same generic that is listed in the Generics example will render like this with it’s specalizers disabled..

Generic (example-generic arg1 arg2 &optional arg3)

A test generic function.

Methods

Methods can also be documented separate to the Generic they implement. This is for cases where the method might define vastly different behaviour to the generic. Or maybe you want to group all the methods that relate to a CLOS Class with that object’s documentation rather than having users jump generics page to verify what types are specialized.

.. cl:method:: symbol-name (specializer)

The :cl:method emits the documentation for generic method specializers:

.. cl:method:: example-generic example-class :test

For the time being, all specializing arguments that aren’t in the current package must be qualified with a package, e.g., common-lisp:t

Code

(defmethod example-generic ((arg1 example-class) (arg2 (eql :test)) &optional arg3)
  "This is the first specialized version of example-generic."
  (list arg1 arg2 arg3))

Output

Method (example-generic (arg1 EXAMPLE-CLASS) (arg2 (eql :TEST)) &optional arg3)

(setf (example-generic (arg1 EXAMPLE-CLASS) (arg2 (eql :TEST))) (new-value T))

This is the first specialized version of example-generic.

See also: example-generic

Disable inheriting documentation

Note: The output for a specializing method will include its parent generic function’s documentation string if there is no documentation for the method, i.e., specializing methods will inherit their parent generic’s docstring. The :noinherit: option suppresses this behaviour and will result in no docstring:

.. cl:method:: example-generic example-class :test1
   :noinherit:

This will be useful if you want to specify a completely custom documentation string in the generated documentation. The output will look like.

Method (example-generic (arg1 EXAMPLE-CLASS) (arg2 (eql :TEST1)) &optional arg3)

See also: example-generic

Disable linking to the generic

By default all methods will contain a See Also section at the end the links back to the generic that they specialize.

This can be disable by specifying the ::nolinkgeneric:: option:

.. cl:method:: example-generic example-class :test
   :nolinkgeneric:

The output will look like.

Method (example-generic (arg1 EXAMPLE-CLASS) (arg2 (eql :TEST)) &optional arg3)

(setf (example-generic (arg1 EXAMPLE-CLASS) (arg2 (eql :TEST))) (new-value T))

This is the first specialized version of example-generic.