.. cl:package:: sphinxcontrib.cldomain.doc

Generics
--------

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

.. rst:directive:: .. cl:generic:: symbol-name

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

       .. cl:generic:: example-generic

Code
~~~~
.. code-block:: common-lisp

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

Output
~~~~~~
.. cl:generic:: example-generic


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..

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


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.

.. rst:directive:: .. 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
~~~~

.. code-block:: common-lisp

  (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
~~~~~~

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


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.

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


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.

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