The documentation-utils Reference Manual

This is the documentation-utils Reference Manual, version 1.2.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 16:18:42 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 documentation-utils

A few simple tools to help you with documenting your library.

Maintainer

Yukari Hafner <>

Author

Yukari Hafner <>

Home Page

https://Shinmera.github.io/documentation-utils/

Source Control

(GIT https://github.com/Shinmera/documentation-utils.git)

Bug Tracker

https://github.com/Shinmera/documentation-utils/issues

License

zlib

Version

1.2.0

Dependency

trivial-indent (system).

Source

documentation-utils.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 documentation-utils/documentation-utils.asd

Source

documentation-utils.asd.

Parent Component

documentation-utils (system).

ASDF Systems

documentation-utils.


3.1.2 documentation-utils/package.lisp

Source

documentation-utils.asd.

Parent Component

documentation-utils (system).

Packages

documentation-utils.


3.1.3 documentation-utils/toolkit.lisp

Dependency

package.lisp (file).

Source

documentation-utils.asd.

Parent Component

documentation-utils (system).

Public Interface
Internals

3.1.4 documentation-utils/documentation.lisp

Dependency

toolkit.lisp (file).

Source

documentation-utils.asd.

Parent Component

documentation-utils (system).


4 Packages

Packages are listed by definition order.


4.1 documentation-utils

Source

package.lisp.

Nicknames
  • docs
  • org.shirakumo.documentation-utils
Use List

common-lisp.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Special variables

Special Variable: *default-formatter*

Variable for the default formatter to use.

This should be either a DOCUMENTATION-FORMATTER instance, or a symbol naming the class of one.

By default this value is an instance of PLAIN-FORMATTER.

See DOCUMENTATION-FORMATTER
See PLAIN-FORMATTER
See DEFINE-DOCS

Package

documentation-utils.

Source

toolkit.lisp.

Special Variable: *documentation-tests*

Holds an alist of documentation types to test functions.

The function should take one argument, the specifier, and return non-NIL if the symbol is bound for the given type.

Package

documentation-utils.

Source

toolkit.lisp.

Special Variable: *documentation-translators*

Holds an alist of documentation types to translator functions.

The function should take one argument, the specifier expression, and return a documentation form suitable to access the documentation for the given type.

Package

documentation-utils.

Source

toolkit.lisp.


5.1.2 Macros

Macro: define-docs (&body expressions)

Allows you to comfortably and easily set the documentation for your library.

Each expression in the body can either take a two or many argument structure. In the two argument structure, the type is implicitly assumed to be FUNCTION. The first argument is then the specifier, and the second the documentation. In the many argument structure the first argument is the type, the last is the documentation, and everything in between the specifier.

The expansion of the documentation accessor –and thus the structure of
the specifier– is dependant on the applicable documentation translator.
By default, the expansion is simply (CL:DOCUMENTATION SPECIFIER TYPE).

In addition to the actual documentation expressions, the docs definition may begin with a set of keyword-value pairs. These options supply initargs for the documentation formatter. By default, the formatter is *DEFAULT-FORMATTER*, but a formatter class of your own can be selected with the :FORMATTER option. This formatter will then translate the documentation expression at compile time to reduce it into a docstring as expected by the underlying documentation storage. Note that the initarg values are used at macroexpansion time, and so are used as literals. If the chosen formatter is already a formatter instance, the initargs are used with REINITIALIZE-INSTANCE. Otherwise if the formatter is a symbol, MAKE-INSTANCE Is used.

See *DOCUMENTATION-TRANSLATORS*
See FORMAT-DOCUMENTATION
See *DEFAULT-FORMATTER*

Package

documentation-utils.

Source

toolkit.lisp.

Macro: define-documentation-alias (alias type)

Shorthand to define an alias to a translator.

This simply sets a delegating function that refers to the given type.

See *DOCUMENTATION-TRANSLATORS*

Package

documentation-utils.

Source

toolkit.lisp.

Macro: define-documentation-test (type args &body body)

Shorthand to define a documentation test function.

See *DOCUMENTATION-TESTS*

Package

documentation-utils.

Source

toolkit.lisp.

Macro: define-documentation-translator (type args &body body)

Shorthand to define a documentation translator function.

See *DOCUMENTATION-TRANSLATORS*

Package

documentation-utils.

Source

toolkit.lisp.


5.1.3 Ordinary functions

Function: check (&key package internal)

Checks whether all symbols have documentation for all known types.

If documentation is not set for a given symbol and type combination, a warning is signalled.

See *DOCUMENTATION-TESTS*

Package

documentation-utils.

Source

toolkit.lisp.

Function: documentation-test (type)

Access the documentation test function for the given type.

See *DOCUMENTATION-TESTS*

Package

documentation-utils.

Source

toolkit.lisp.

Function: (setf documentation-test) (type)
Package

documentation-utils.

Source

toolkit.lisp.

Function: documentation-translator (type)

Access the documentation translator function for the given type.

See *DOCUMENTATION-TRANSLATORS*

Package

documentation-utils.

Source

toolkit.lisp.

Function: (setf documentation-translator) (type)
Package

documentation-utils.

Source

toolkit.lisp.

Function: remove-documentation-test (type)

Remove the documentation test function for the given type.

See *DOCUMENTATION-TESTS*

Package

documentation-utils.

Source

toolkit.lisp.

Function: remove-documentation-translator (type)

Remove the documentation translator function for the given type.

See *DOCUMENTATION-TRANSLATORS*

Package

documentation-utils.

Source

toolkit.lisp.


5.1.4 Generic functions

Generic Function: format-documentation (formatter type var documentation)

Processes the documentation string according to the formatter’s rules.

Passed along are the three values that make up a documentation definition:

- The fundamental type of the definition as used in DOCUMENTATION.
- An additional set of variants used to distinguish more complicated definitions. For instance, for methods this would be the method qualifiers. - The expression used for the actual documentation. This is always the last expression within a documentation definition expression.

The function should either error on an invalid documentation expression, or return a string to be passed to the underlying documentation storage.

You may use this function to store the documentation expression elsewhere so that it may be processed into different formats using additional markup than is appropriate for plain strings.

See DOCUMENTATION-FORMATTER

Package

documentation-utils.

Source

toolkit.lisp.

Methods
Method: format-documentation ((formatter plain-formatter) type var documentation)

5.1.5 Classes

Class: documentation-formatter

Base class for all documentation formatters.

A documentation formatter is responsible for translating user-defined documentation expressions into docstrings usable by the underlying documentation storage. This can also be used to hook it into other systems that access documentation and may enrich it with further styling or information.

The only relevant function for this class is FORMAT-DOCUMENTATION, which is used to perform the translation.

See FORMAT-DOCUMENTATION

Package

documentation-utils.

Source

toolkit.lisp.

Direct subclasses

plain-formatter.


5.2 Internals


5.2.1 Ordinary functions

Function: list-symbols (package &key internal)
Package

documentation-utils.

Source

toolkit.lisp.

Function: removef (plist &rest keys)

Removes the given set of keys from the plist and returns a fresh copy.

Package

documentation-utils.

Source

toolkit.lisp.

Function: split-body-options (body)

Splits the body of expressions into two parts, a plist, and a body.

Returned are two values: a plist, and a body. The plist is composed of all keyword-value pairs found at the beginning of the body. The returned body is all the remaining expressions.

Package

documentation-utils.

Source

toolkit.lisp.


5.2.2 Classes

Class: plain-formatter

A formatter that only allows strings and emits them verbatim.

This is the default formatter.

See DOCUMENTATION-FORMATTER

Package

documentation-utils.

Source

toolkit.lisp.

Direct superclasses

documentation-formatter.

Direct methods

format-documentation.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
C   D   F   G   L   M   R   S  
Index Entry  Section

(
(setf documentation-test): Public ordinary functions
(setf documentation-translator): Public ordinary functions

C
check: Public ordinary functions

D
define-docs: Public macros
define-documentation-alias: Public macros
define-documentation-test: Public macros
define-documentation-translator: Public macros
documentation-test: Public ordinary functions
documentation-translator: Public ordinary functions

F
format-documentation: Public generic functions
format-documentation: Public generic functions
Function, (setf documentation-test): Public ordinary functions
Function, (setf documentation-translator): Public ordinary functions
Function, check: Public ordinary functions
Function, documentation-test: Public ordinary functions
Function, documentation-translator: Public ordinary functions
Function, list-symbols: Private ordinary functions
Function, remove-documentation-test: Public ordinary functions
Function, remove-documentation-translator: Public ordinary functions
Function, removef: Private ordinary functions
Function, split-body-options: Private ordinary functions

G
Generic Function, format-documentation: Public generic functions

L
list-symbols: Private ordinary functions

M
Macro, define-docs: Public macros
Macro, define-documentation-alias: Public macros
Macro, define-documentation-test: Public macros
Macro, define-documentation-translator: Public macros
Method, format-documentation: Public generic functions

R
remove-documentation-test: Public ordinary functions
remove-documentation-translator: Public ordinary functions
removef: Private ordinary functions

S
split-body-options: Private ordinary functions