The documentation-utils-extensions Reference Manual

Table of Contents

The documentation-utils-extensions Reference Manual

This is the documentation-utils-extensions Reference Manual, version 0.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Fri Jun 26 10:58:09 2020 GMT+0.

1 Introduction

documentation-utils-extensions

Set of extensions for documentation-utils.

About

Use rich-formatter to format documentation with sections :syntax, :arguments, :examples, :description, :returns, :side-effects, :thread-safety, :affected-by, :see-also and :notes. Gather unformatted input by using rich-aggregating-formatter and *DOCUMENTATION* variable. Find gathered documentation with find-documentation function. Execute code stored in documentation with execute-documentation. See examples in the src/documentation.lisp file. See documentation-utils system for more info.

Tested under SBCL and CCL. Should work on other implementations as well.

2 Systems

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

2.1 documentation-utils-extensions

Maintainer

Marek Kochanowicz

Author

Marek Kochanowicz

License

MIT

Description

Set of extensions for documentation-utils.

Version

0.0.0

Dependency

documentation-utils

Source

documentation-utils-extensions.asd (file)

Components

• package.lisp (file)
• classes.lisp (file)
• variables.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.

3.1 Lisp

3.1.1 documentation-utils-extensions.asd

Location

/home/quickref/quicklisp/dists/quicklisp/software/documentation-utils-extensions-20180711-git/documentation-utils-extensions.asd

Systems

documentation-utils-extensions (system)

3.1.2 documentation-utils-extensions/package.lisp

Parent

documentation-utils-extensions (system)

Location

package.lisp

Packages

documentation-utils-extensions

3.1.3 documentation-utils-extensions/classes.lisp

Dependency

package.lisp (file)

Parent

documentation-utils-extensions (system)

Location

classes.lisp

Exported Definitions

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

Internal Definitions

read-content (method)

3.1.4 documentation-utils-extensions/variables.lisp

Dependency

classes.lisp (file)

Parent

documentation-utils-extensions (system)

Location

variables.lisp

Exported Definitions

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

3.1.5 documentation-utils-extensions/methods.lisp

Dependency

variables.lisp (file)

Parent

documentation-utils-extensions (system)

Location

methods.lisp

Internal Definitions

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

3.1.6 documentation-utils-extensions/functions.lisp

Dependency

methods.lisp (file)

Parent

documentation-utils-extensions (system)

Location

functions.lisp

Exported Definitions

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

3.1.7 documentation-utils-extensions/documentation.lisp

Dependency

functions.lisp (file)

Parent

documentation-utils-extensions (system)

Location

documentation.lisp

4 Packages

Packages are listed by definition order.

4.1 documentation-utils-extensions

Source

package.lisp (file)

Nickname

docs.ext

Use List

common-lisp

Exported Definitions

• *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 function)
• read-documentation-sections (method)
• rich-aggregating-formatter (class)
• rich-formatter (class)
• select-documentation (function)

Internal Definitions

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

5 Definitions

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

5.1 Exported definitions

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

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

5.1.2 Functions

Function: clear-documentation ()

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

Package

documentation-utils-extensions

Source

functions.lisp (file)

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

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

Function: make-documentation-collection ()

Package

documentation-utils-extensions

Source

classes.lisp (file)

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

5.1.3 Generic functions

Generic Function: read-documentation-sections OBJECT

Package

documentation-utils-extensions

Methods

Method: read-documentation-sections (RICH-FORMATTER rich-formatter)

automatically generated reader method

Source

classes.lisp (file)

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

Direct superclasses

documentation-formatter (class)

Direct subclasses

rich-aggregating-formatter (class)

Direct methods

format-documentation (method)

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

documentation-utils-extensions

Source

classes.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• %select-documentation (method)
• insert-documentation (method)
• %find-documentation (method)
• %clear-documentation (method)
• reinitialize-instance (method)
• read-content (method)

Direct slots

Slot: %content

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

Type

hash-table

Initform

(make-hash-table)

Readers

read-content (generic function)

Class: rich-aggregating-formatter ()

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

Package

documentation-utils-extensions

Source

classes.lisp (file)

Direct superclasses

• rich-formatter (class)
• aggregating-formatter (class)

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

documentation-utils-extensions

Source

classes.lisp (file)

Direct superclasses

documentation-formatter (class)

Direct subclasses

rich-aggregating-formatter (class)

Direct methods

• format-documentation (method)
• format-to-stream (method)
• read-documentation-sections (method)

Direct slots

Slot: %documentation-sections

Initargs

:documentation-sections

Initform

documentation-utils-extensions:*documentation-sections*

Readers

read-documentation-sections (generic function)

5.2 Internal definitions

5.2.1 Generic functions

Generic Function: %clear-documentation DOCUMENTATION

Package

documentation-utils-extensions

Source

methods.lisp (file)

Methods

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

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

Generic Function: %find-documentation DOCUMENTATION TYPE NAME

Package

documentation-utils-extensions

Source

methods.lisp (file)

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

documentation-utils-extensions

Source

methods.lisp (file)

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

documentation-utils-extensions

Source

methods.lisp (file)

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

documentation-utils-extensions

Source

methods.lisp (file)

Methods

Method: insert-documentation (DOCUMENTATION (eql nil)) TYPE NAME ARGUMENTS

Method: insert-documentation (DOCUMENTATION documentation-collection) TYPE NAME ARGUMENTS

Generic Function: read-content OBJECT

Package

documentation-utils-extensions

Methods

Method: read-content (DOCUMENTATION-COLLECTION documentation-collection)

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

Source

classes.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types