The documentation-utils-extensions Reference Manual

Child Components

package.lisp (file).
variables.lisp (file).
classes.lisp (file).
methods.lisp (file).
functions.lisp (file).
documentation.lisp (file).

3 Files

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

Lisp

3.1.3 `documentation-utils-extensions/variables.lisp`

Dependency

package.lisp (file).

Source

Parent Component

Public Interface

*documentation* (special variable).
*documentation-sections* (special variable).

3.1.4 `documentation-utils-extensions/classes.lisp`

Dependency

variables.lisp (file).

Source

Parent Component

Public Interface

aggregating-formatter (class).
documentation-collection (class).
make-documentation-collection (function).
read-documentation-sections (reader method).
rich-aggregating-formatter (class).
rich-formatter (class).

Internals

read-content (reader method).

3.1.5 `documentation-utils-extensions/methods.lisp`

Dependency

classes.lisp (file).

Source

Parent Component

Public Interface

format-documentation (method).
format-documentation (method).
reinitialize-instance (method).

Internals

%clear-documentation (generic function).
%find-documentation (generic function).
%select-documentation (generic function).
format-to-stream (generic function).
insert-documentation (generic function).

3.1.6 `documentation-utils-extensions/functions.lisp`

Dependency

methods.lisp (file).

Source

Parent Component

Public Interface

clear-documentation (function).
execute-documentation (function).
find-documentation (function).
select-documentation (function).

3.1.7 `documentation-utils-extensions/documentation.lisp`

Dependency: functions.lisp (file).
Source: documentation-utils-extensions.asd.
Parent Component: documentation-utils-extensions (system).

4 Packages

Packages are listed by definition order.

documentation-utils-extensions

4.1 `documentation-utils-extensions`

Source

package.lisp.

Nickname

docs.ext

Use List

common-lisp.

Public Interface

*documentation* (special variable).
*documentation-sections* (special variable).
aggregating-formatter (class).
clear-documentation (function).
documentation-collection (class).
execute-documentation (function).
find-documentation (function).
make-documentation-collection (function).
read-documentation-sections (generic reader).
rich-aggregating-formatter (class).
rich-formatter (class).
select-documentation (function).

Internals

%clear-documentation (generic function).
%find-documentation (generic function).
%select-documentation (generic function).
format-to-stream (generic function).
insert-documentation (generic function).
read-content (generic reader).

5 Definitions

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

Public Interface
Internals

5.1.1 Special variables

Special Variable: *documentation* ¶

Examples:
–Disable gathering, (defparameter docs.ext:*documentation* nil)
–Enable gathering, (defparameter docs.ext:*documentation* (docs.ext:make-documentation-collection))

Package: documentation-utils-extensions.
Source: variables.lisp.

Special Variable: *documentation-sections* ¶

Description:
Alist used by RICH-FORMATTER to determine sections of documentation. Maps symbols to section names.. RICH-FORMATTER will always use order of formatting identical to that provided by this list.

Package: documentation-utils-extensions.
Source: variables.lisp.

5.1.2 Ordinary functions

Function: clear-documentation () ¶

Description:
Removes everything from *DOCUMENTATION*. Does nothing if *DOCUMENTATION* is bound to nil.

Package: documentation-utils-extensions.
Source: functions.lisp.

Function: execute-documentation (&key package label type) ¶

Description:
Calls SELECT-DOCUMENTATION first, then attempts to read-from-string, compile and execute each result. Works with sections containing pure strings as well as lists of strings. In the second case, whole paragraph is executed in one go.

Returns:
Always nil

Exceptional situations:
Does not attempt to handle errors signaled by either read or compile. Simply assumes that paragraph should contain valid Lisp code.

Notes:
This function is used most often with respect to :EXAMPLES section.

Package: documentation-utils-extensions.
Source: functions.lisp.

Function: find-documentation (type name) ¶

Arguments:
–TYPE, Type, as specified by documentation-utils.
–NAME, Name, as specified by documentation-utils.

Description:
Attempts to find aggregated documentation. Will fail if *DOCUMENTATION* is bound to nil, or there is no object of type and name in it.

Returns:
–FIRST, Arguments, as passed to the formatter. NIL if not found.
–SECOND, Boolean. T if documentation was found, NIL otherwise.

Package: documentation-utils-extensions.
Source: functions.lisp.

Function: make-documentation-collection () ¶

Package: documentation-utils-extensions.
Source: classes.lisp.

Function: select-documentation (&key package label type) ¶

Description:
Selects all sections with LABEL from *documentation* documenting object named by symbols from PACKAGE and TYPE. LABEL, PACKAGE and TYPE may be: just a symbol, list of symbols (will return union) or nil (will disable filtering).

Package: documentation-utils-extensions.
Source: functions.lisp.

5.1.3 Generic functions

Generic Reader: read-documentation-sections (object) ¶

Package

Methods

Reader Method: read-documentation-sections ((rich-formatter rich-formatter)) ¶

automatically generated reader method

Source: classes.lisp.
Target Slot: %documentation-sections.

5.1.4 Standalone methods

Method: format-documentation :after ((formatter aggregating-formatter) type name arguments) ¶

Package: documentation-utils.
Source: methods.lisp.

Method: format-documentation ((formatter rich-formatter) type name (arguments list)) ¶

Package: documentation-utils.
Source: methods.lisp.

Method: reinitialize-instance ((documentation documentation-collection) &rest initargs) ¶

Source: methods.lisp.

5.1.5 Classes

Class: aggregating-formatter ¶

Description:
Use subclass of this formatter to enable documentation gathering into *DOCUMENTATION*

Notes:
Existing format-documentation specialization uses :after specializer. This approach is condition safe.

Package: documentation-utils-extensions.
Source: classes.lisp.
Direct superclasses: documentation-formatter.
Direct subclasses: rich-aggregating-formatter.
Direct methods: format-documentation.

Class: documentation-collection ¶

Description:
Class used to map type and name to arguments of define-docs.

Notes:
See MAKE-DOCUMENTATION-COLLECTION, *DOCUMENTATION* and FIND-DOCUMENTATION for more information.

Package

Source

classes.lisp.

Direct methods

%clear-documentation.
%find-documentation.
%select-documentation.
insert-documentation.
read-content.
reinitialize-instance.

Direct slots

Slot: %content ¶

Stores tree as nested hash-table: type>name>original arguments

Type: hash-table
Initform: (make-hash-table)
Readers: read-content.
Writers: This slot is read-only.

Class: rich-aggregating-formatter ¶

Description:
Combines rich-formatter and aggregating formatter into one class.

Package

Source

classes.lisp.

Direct superclasses

aggregating-formatter.
rich-formatter.

Class: rich-formatter ¶

Description:
Subclass of documentation-formatter, with rich formatting arguments. Those include: :arguments, :examples, :description, :returns, :side-effects and :notes.

Notes:
–Will simply ignore unknown arguments.
–Values passed may be in the form of strings, or lists.
–Nested lists (just first level) are printed using (format stream " –~{~a~^, ~}~%" x).
–Above is handy when specifing (for instance) :arguments. First element of list may designate argument name, second can contain description of the argument.

Package

rich-aggregating-formatter.

Source

classes.lisp.

Direct superclasses

documentation-formatter.

Direct subclasses

Direct methods

format-documentation.
format-to-stream.
read-documentation-sections.

Direct slots

Slot: %documentation-sections ¶

Initform: documentation-utils-extensions:*documentation-sections*
Initargs: :documentation-sections
Readers: read-documentation-sections.
Writers: This slot is read-only.

5.2 Internals

Generic functions

5.2.1 Generic functions

Generic Function: %clear-documentation (documentation) ¶

Package

Source

Methods

Method: %clear-documentation ((documentation (eql nil))) ¶

Method: %clear-documentation ((documentation documentation-collection)) ¶

Generic Function: %find-documentation (documentation type name) ¶

Package

Source

Methods

Method: %find-documentation ((documentation-collection (eql nil)) type name) ¶

Method: %find-documentation ((documentation documentation-collection) type name) ¶

Generic Function: %select-documentation (documentation package label type) ¶

Package

Source

Methods

Method: %select-documentation ((documentation documentation-collection) package label type) ¶

Method: %select-documentation ((documentation (eql nil)) package label type) ¶

Generic Function: format-to-stream (formatter stream section-name documentation-form first-item) ¶

Package

Source

Methods

Method: format-to-stream (formatter stream section-name (arguments list) first-item) ¶

Method: format-to-stream ((formatter rich-formatter) stream (section-name string) arguments first-item) ¶

Method: format-to-stream (formatter stream section-name (arguments string) first-item) ¶

Generic Function: insert-documentation (documentation type name arguments) ¶

Package

Source

Methods

Method: insert-documentation ((documentation (eql nil)) type name arguments) ¶

Method: insert-documentation ((documentation documentation-collection) type name arguments) ¶

Generic Reader: read-content (object) ¶

Package