The documentation-utils Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The documentation-utils Reference Manual

This is the documentation-utils Reference Manual, version 1.1.0, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 11:42:31 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

About documentation-utils

This is a small library to help you with managing the docstrings for your library.

How To

The central element is the define-docs macro. It takes a body of expressions to define the documentation. In the simplest form, this looks like so:

(docs:define-docs
  (my-function "Some documentation"))

If you need a different type of documentation, or want to be explicit, prepend its type to the expression.

(docs:define-docs
  (function my-function "Some documentation")
  (variable *my-variable* "Something else"))

In order to make things look more homely, aliases exist that can be used instead:

(docs:define-docs
  (defun my-function
    "Some documentation")
  (defvar *my-variable*
    "Something else"))

Aliases exist for most of the def* expressions. Some expressions can take multiple arguments for the specifier, but the last in the expression is always the docstring:

(docs:define-docs
  (defmethod foo :append ((num integer) other)
    "stuff"))

You can also extend this system for your own documentation translators. If you need more complex behaviour than the default of (documentation specifier type), see define-documentation-translator. If you are defining a new documentation type, you should also add a documentation-test to ensure that check can verify that you actually did set a documentation.

Custom Documentation Syntax

In case you would like to use a richer markup than plaintext within your documentation, you can use the formatter facility. Formatters take the last expression in a documentation definition expression and translate it to a docstring. This means that, with the right formatter, you can use a format other than plain docstrings, or even hook this into another documentation processing system in order to emit richer text while staying compatible to the standard cl:documentation facility.

In order to switch the formatter, you can use the define-docs options like so:

(docs:define-docs
  :formatter my-formatter
  (function my-function
    (:arguments (a "Something about this"
                 b "Something about that")
     :return-value "Nothing useful"
     :summary "This function does something, though I don't know what.")))

Aside from the :formatter option, you can pass an arbitrary number of other options as well, which will be used as initargs for the formatter instance. Note that this is all done at macroexpansion-time, and the initarg values are thus used as literals.

The formatter presented above is just an example and is not provided by documentation-utils. Since I can't anticipate people's overall preferences in documentation style, it is up to you to write something more complicated to extend documentation-utils capabilities. Doing so should just be a matter of subclassing formatter and adding a method to format-documentation, though. As an example, the above could be done as follows:

(defclass my-formatter (formatter) ())

(defmethod format-documentation ((formatter my-formatter) type var docs)
  (format NIL "~a~@[

Arguments:~{
  ~a: ~a~}~]~@[

Return value:
  ~a~]"
          (getf docs :summary)
          (getf docs :arguments)
          (getf docs :return-value)))

I'm sure you can imagine your own way of doing things.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 documentation-utils

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

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

License

Artistic

Description

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

Version

1.1.0

Dependency

trivial-indent

Source

documentation-utils.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 documentation-utils.asd

Location

documentation-utils.asd

Systems

documentation-utils (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 documentation-utils/package.lisp

Parent

documentation-utils (system)

Location

package.lisp

Packages

documentation-utils


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 documentation-utils/toolkit.lisp

Dependency

package.lisp (file)

Parent

documentation-utils (system)

Location

toolkit.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.4 documentation-utils/documentation.lisp

Dependency

toolkit.lisp (file)

Parent

documentation-utils (system)

Location

documentation.lisp


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 documentation-utils

Source

package.lisp (file)

Nicknames
Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

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 (file)

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 (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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

See *DOCUMENTATION-TRANSLATORS*
See FORMAT-DOCUMENTATION
See PLAIN-FORMATTER

Package

documentation-utils

Source

toolkit.lisp (file)

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 (file)

Macro: define-documentation-test TYPE ARGS &body BODY

Shorthand to define a documentation test function.

See *DOCUMENTATION-TESTS*

Package

documentation-utils

Source

toolkit.lisp (file)

Macro: define-documentation-translator TYPE ARGS &body BODY

Shorthand to define a documentation translator function.

See *DOCUMENTATION-TRANSLATORS*

Package

documentation-utils

Source

toolkit.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 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 (file)

Function: documentation-test TYPE

Access the documentation test function for the given type.

See *DOCUMENTATION-TESTS*

Package

documentation-utils

Source

toolkit.lisp (file)

Writer

(setf documentation-test) (function)

Function: (setf documentation-test) TEST TYPE
Package

documentation-utils

Source

toolkit.lisp (file)

Reader

documentation-test (function)

Function: documentation-translator TYPE

Access the documentation translator function for the given type.

See *DOCUMENTATION-TRANSLATORS*

Package

documentation-utils

Source

toolkit.lisp (file)

Writer

(setf documentation-translator) (function)

Function: (setf documentation-translator) TRANSLATOR TYPE
Package

documentation-utils

Source

toolkit.lisp (file)

Reader

documentation-translator (function)

Function: remove-documentation-test TYPE

Remove the documentation test function for the given type.

See *DOCUMENTATION-TESTS*

Package

documentation-utils

Source

toolkit.lisp (file)

Function: remove-documentation-translator TYPE

Remove the documentation translator function for the given type.

See *DOCUMENTATION-TRANSLATORS*

Package

documentation-utils

Source

toolkit.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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 (file)

Methods
Method: format-documentation (FORMATTER plain-formatter) TYPE VAR DOCUMENTATION

Previous: , Up: Exported definitions   [Contents][Index]

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 (file)

Direct superclasses

standard-object (class)

Direct subclasses

plain-formatter (class)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Functions

Function: list-symbols PACKAGE &key INTERNAL
Package

documentation-utils

Source

toolkit.lisp (file)

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 (file)

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 (file)


Previous: , Up: Internal definitions   [Contents][Index]

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 (file)

Direct superclasses

documentation-formatter (class)

Direct methods

format-documentation (method)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   D   F   L  
Index Entry  Section

D
documentation-utils.asd: The documentation-utils<dot>asd file
documentation-utils/documentation.lisp: The documentation-utils/documentation<dot>lisp file
documentation-utils/package.lisp: The documentation-utils/package<dot>lisp file
documentation-utils/toolkit.lisp: The documentation-utils/toolkit<dot>lisp file

F
File, Lisp, documentation-utils.asd: The documentation-utils<dot>asd file
File, Lisp, documentation-utils/documentation.lisp: The documentation-utils/documentation<dot>lisp file
File, Lisp, documentation-utils/package.lisp: The documentation-utils/package<dot>lisp file
File, Lisp, documentation-utils/toolkit.lisp: The documentation-utils/toolkit<dot>lisp file

L
Lisp File, documentation-utils.asd: The documentation-utils<dot>asd file
Lisp File, documentation-utils/documentation.lisp: The documentation-utils/documentation<dot>lisp file
Lisp File, documentation-utils/package.lisp: The documentation-utils/package<dot>lisp file
Lisp File, documentation-utils/toolkit.lisp: The documentation-utils/toolkit<dot>lisp file

Jump to:   D   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

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

(
(setf documentation-test): Exported functions
(setf documentation-translator): Exported functions

C
check: Exported functions

D
define-docs: Exported macros
define-documentation-alias: Exported macros
define-documentation-test: Exported macros
define-documentation-translator: Exported macros
documentation-test: Exported functions
documentation-translator: Exported functions

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

G
Generic Function, format-documentation: Exported generic functions

L
list-symbols: Internal functions

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

R
remove-documentation-test: Exported functions
remove-documentation-translator: Exported functions
removef: Internal functions

S
split-body-options: Internal functions

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

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*documentation-tests*: Exported special variables
*documentation-translators*: Exported special variables

S
Special Variable, *documentation-tests*: Exported special variables
Special Variable, *documentation-translators*: Exported special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   D   P   S  
Index Entry  Section

C
Class, documentation-formatter: Exported classes
Class, plain-formatter: Internal classes

D
documentation-formatter: Exported classes
documentation-utils: The documentation-utils system
documentation-utils: The documentation-utils package

P
Package, documentation-utils: The documentation-utils package
plain-formatter: Internal classes

S
System, documentation-utils: The documentation-utils system

Jump to:   C   D   P   S