The documentation-utils-extensions Reference Manual

Table of Contents

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

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 Wed Feb 19 20:24:56 2020 GMT+0.


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

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.


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

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

Location

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

Systems

documentation-utils-extensions (system)


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

3.1.2 documentation-utils-extensions/package.lisp

Parent

documentation-utils-extensions (system)

Location

package.lisp

Packages

documentation-utils-extensions


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

3.1.3 documentation-utils-extensions/classes.lisp

Dependency

package.lisp (file)

Parent

documentation-utils-extensions (system)

Location

classes.lisp

Exported Definitions
Internal Definitions

read-content (method)


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

3.1.4 documentation-utils-extensions/variables.lisp

Dependency

classes.lisp (file)

Parent

documentation-utils-extensions (system)

Location

variables.lisp

Exported Definitions

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

3.1.5 documentation-utils-extensions/methods.lisp

Dependency

variables.lisp (file)

Parent

documentation-utils-extensions (system)

Location

methods.lisp

Internal Definitions

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

3.1.6 documentation-utils-extensions/functions.lisp

Dependency

methods.lisp (file)

Parent

documentation-utils-extensions (system)

Location

functions.lisp

Exported Definitions

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

3.1.7 documentation-utils-extensions/documentation.lisp

Dependency

functions.lisp (file)

Parent

documentation-utils-extensions (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-extensions

Source

package.lisp (file)

Nickname

docs.ext

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*

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)


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

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)


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

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)


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

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
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
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
Direct slots
Slot: %documentation-sections
Initargs

:documentation-sections

Initform

documentation-utils-extensions:*documentation-sections*

Readers

read-documentation-sections (generic function)


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

5.2 Internal definitions


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

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)


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-extensions.asd: The documentation-utils-extensions․asd file
documentation-utils-extensions/classes.lisp: The documentation-utils-extensions/classes․lisp file
documentation-utils-extensions/documentation.lisp: The documentation-utils-extensions/documentation․lisp file
documentation-utils-extensions/functions.lisp: The documentation-utils-extensions/functions․lisp file
documentation-utils-extensions/methods.lisp: The documentation-utils-extensions/methods․lisp file
documentation-utils-extensions/package.lisp: The documentation-utils-extensions/package․lisp file
documentation-utils-extensions/variables.lisp: The documentation-utils-extensions/variables․lisp file

F
File, Lisp, documentation-utils-extensions.asd: The documentation-utils-extensions․asd file
File, Lisp, documentation-utils-extensions/classes.lisp: The documentation-utils-extensions/classes․lisp file
File, Lisp, documentation-utils-extensions/documentation.lisp: The documentation-utils-extensions/documentation․lisp file
File, Lisp, documentation-utils-extensions/functions.lisp: The documentation-utils-extensions/functions․lisp file
File, Lisp, documentation-utils-extensions/methods.lisp: The documentation-utils-extensions/methods․lisp file
File, Lisp, documentation-utils-extensions/package.lisp: The documentation-utils-extensions/package․lisp file
File, Lisp, documentation-utils-extensions/variables.lisp: The documentation-utils-extensions/variables․lisp file

L
Lisp File, documentation-utils-extensions.asd: The documentation-utils-extensions․asd file
Lisp File, documentation-utils-extensions/classes.lisp: The documentation-utils-extensions/classes․lisp file
Lisp File, documentation-utils-extensions/documentation.lisp: The documentation-utils-extensions/documentation․lisp file
Lisp File, documentation-utils-extensions/functions.lisp: The documentation-utils-extensions/functions․lisp file
Lisp File, documentation-utils-extensions/methods.lisp: The documentation-utils-extensions/methods․lisp file
Lisp File, documentation-utils-extensions/package.lisp: The documentation-utils-extensions/package․lisp file
Lisp File, documentation-utils-extensions/variables.lisp: The documentation-utils-extensions/variables․lisp file

Jump to:   D   F   L  

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

A.2 Functions

Jump to:   %  
C   E   F   G   I   M   R   S  
Index Entry  Section

%
%clear-documentation: Internal generic functions
%clear-documentation: Internal generic functions
%clear-documentation: Internal generic functions
%find-documentation: Internal generic functions
%find-documentation: Internal generic functions
%find-documentation: Internal generic functions
%select-documentation: Internal generic functions
%select-documentation: Internal generic functions
%select-documentation: Internal generic functions

C
clear-documentation: Exported functions

E
execute-documentation: Exported functions

F
find-documentation: Exported functions
format-to-stream: Internal generic functions
format-to-stream: Internal generic functions
format-to-stream: Internal generic functions
format-to-stream: Internal generic functions
Function, clear-documentation: Exported functions
Function, execute-documentation: Exported functions
Function, find-documentation: Exported functions
Function, make-documentation-collection: Exported functions
Function, select-documentation: Exported functions

G
Generic Function, %clear-documentation: Internal generic functions
Generic Function, %find-documentation: Internal generic functions
Generic Function, %select-documentation: Internal generic functions
Generic Function, format-to-stream: Internal generic functions
Generic Function, insert-documentation: Internal generic functions
Generic Function, read-content: Internal generic functions
Generic Function, read-documentation-sections: Exported generic functions

I
insert-documentation: Internal generic functions
insert-documentation: Internal generic functions
insert-documentation: Internal generic functions

M
make-documentation-collection: Exported functions
Method, %clear-documentation: Internal generic functions
Method, %clear-documentation: Internal generic functions
Method, %find-documentation: Internal generic functions
Method, %find-documentation: Internal generic functions
Method, %select-documentation: Internal generic functions
Method, %select-documentation: Internal generic functions
Method, format-to-stream: Internal generic functions
Method, format-to-stream: Internal generic functions
Method, format-to-stream: Internal generic functions
Method, insert-documentation: Internal generic functions
Method, insert-documentation: Internal generic functions
Method, read-content: Internal generic functions
Method, read-documentation-sections: Exported generic functions

R
read-content: Internal generic functions
read-content: Internal generic functions
read-documentation-sections: Exported generic functions
read-documentation-sections: Exported generic functions

S
select-documentation: Exported functions

Jump to:   %  
C   E   F   G   I   M   R   S  

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

A.3 Variables

Jump to:   %   *  
S  
Index Entry  Section

%
%content: Exported classes
%documentation-sections: Exported classes

*
*documentation*: Exported special variables
*documentation-sections*: Exported special variables

S
Slot, %content: Exported classes
Slot, %documentation-sections: Exported classes
Special Variable, *documentation*: Exported special variables
Special Variable, *documentation-sections*: Exported special variables

Jump to:   %   *  
S  

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

A.4 Data types

Jump to:   A   C   D   P   R   S  
Index Entry  Section

A
aggregating-formatter: Exported classes

C
Class, aggregating-formatter: Exported classes
Class, documentation-collection: Exported classes
Class, rich-aggregating-formatter: Exported classes
Class, rich-formatter: Exported classes

D
documentation-collection: Exported classes
documentation-utils-extensions: The documentation-utils-extensions system
documentation-utils-extensions: The documentation-utils-extensions package

P
Package, documentation-utils-extensions: The documentation-utils-extensions package

R
rich-aggregating-formatter: Exported classes
rich-formatter: Exported classes

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

Jump to:   A   C   D   P   R   S