This is the docparser Reference Manual, version 0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 15 06:00:03 2024 GMT+0.
The main system appears first, followed by any subsystem dependency.
docparserParse documentation from Common Lisp systems.
Fernando Borretti <eudoxiahp@gmail.com>
Fernando Borretti <eudoxiahp@gmail.com>
(GIT )
MIT
# docparser
[](https://travis-ci.org/eudoxia0/docparser)
[](https://coveralls.io/r/eudoxia0/docparser?branch=master)
[](http://quickdocs.org/docparser/)
Extract documentation from Common Lisp systems. Used in the [Codex][codex]
documentation generator and [Quickdocs][qd].
# Overview
Documentation generators generally implement their own (ad hoc,
informally-specified, etc.) version of docstring extraction, and as a result,
every documentation generator extracts a different subset of documentation.
docparser isn’t yet another documentation generator: it is a library for
extracting documentation from Common Lisp systems in a structured manner so you
can build a documentation generator on top of it. It parses systems and returns
a set of objects representing packages, variables, functions, classes, etc. and
their docstrings. It is designed to extract as much information from systems as
possible, and let documentation generators choose what to keep and discard. This
minimizes duplication of effort and separates docstring extraction from
generation.
docparser has classes to represent every documentable Common Lisp construct:
* Functions
* Macros
* Generic functions
* Methods
* Special variables and constants
* Classes and class slots
* Structures
* Conditions
* Type definitions
* Packages
Additionally, docparser has custom subclasses to represent the documentation of
[CFFI][cffi] definitions:
* Foreign functions ([‘defcfun‘][defcfun]).
* Foreign type definitions ([‘defctype‘][defctype]).
* Foreign structure definition ([‘defcstruct‘][defcstruct]).
* Foreign union definitions ([‘defcunion‘][defcunion]).
* Enumerations ([‘defcenum‘][defcenum]).
* Bitfields ([‘defbitfield‘][defbitfield]).
This improves API documentation generation for foreign library wrappers. Note
that, when parsing documentation, docparser catches and ignores foreign library
loading errors, so documentation can be generated even in a machine that can’t
properly load the library. This is useful for documenting libraries with complex
external dependencies.
[codex]: https://github.com/CommonDoc/codex
[qd]: http://quickdocs.org/
[cffi]: https://github.com/cffi/cffi
[defcfun]: https://common-lisp.net/project/cffi/manual/cffi-manual.html#defcfun
[defctype]: https://common-lisp.net/project/cffi/manual/cffi-manual.html#defctype
[defcstruct]: https://common-lisp.net/project/cffi/manual/cffi-manual.html#defcstruct
[defcunion]: https://common-lisp.net/project/cffi/manual/cffi-manual.html#defcunion
[defcenum]: https://common-lisp.net/project/cffi/manual/cffi-manual.html#defcenum
[defbitfield]: https://common-lisp.net/project/cffi/manual/cffi-manual.html#defbitfield
# Usage
To extract documentation from a system (which will be Quickloaded
automatically), do this:
“‘lisp
(docparser:parse :my-system-name)
“‘
This returns an index, which is basically a store of documentation nodes. For a
quick overview of what’s in it, use the ‘dump‘ function:
“‘lisp
CL-USER> (docparser:dump (docparser:parse :cl-yaml))
; some compilation output
Package "YAML.ERROR" with docstring "YAML errors."
#<condition yaml-error>
#<condition parsing-error>
#<condition unsupported-float-value>
Package "YAML.FLOAT" with docstring "Handle IEEE floating point values."
#<variable *float-strategy*>
#<variable *sbcl-nan-value*>
#<function not-a-number NIL>
#<function positive-infinity NIL>
#<function negative-infinity NIL>
Package "YAML.SCALAR" with docstring "Parser for scalar values."
...
“‘
To search for nodes by name or type, you use the ‘query‘ function:
“‘lisp
CL-USER> (defparameter *index* (docparser:parse :cl-yaml))
; some compilation output
*INDEX*
CL-USER> (docparser:query *index* :package-name "CL-YAML")
#(#<generic function parse (INPUT &KEY MULTI-DOCUMENT-P)>
#<method parse ((INPUT STRING) &KEY MULTI-DOCUMENT-P)>
#<method parse ((INPUT PATHNAME) &KEY MULTI-DOCUMENT-P)>
#<function emit (VALUE STREAM)> #<function emit-to-string (VALUE)>)
CL-USER> (docparser:query *index* :package-name "CL-YAML"
:symbol-name "PARSE")
#(#<generic function parse (INPUT &KEY MULTI-DOCUMENT-P)>
#<method parse ((INPUT STRING) &KEY MULTI-DOCUMENT-P)>
#<method parse ((INPUT PATHNAME) &KEY MULTI-DOCUMENT-P)>)
CL-USER> (docparser:query *index* :package-name "CL-YAML"
:symbol-name "PARSE"
:class ’docparser:generic-function-node)
#(#<generic function parse (INPUT &KEY MULTI-DOCUMENT-P)>)
“‘
If you don’t know what the index contains, you can go through it using the
‘do-packages‘ and ‘do-nodes‘ macros:
“‘lisp
CL-USER> (docparser:do-packages (package *index*)
(format t "~&In package: ~A." (docparser:package-index-name package))
(docparser:do-nodes (node package)
(print (class-of node))))
In package: YAML.ERROR.
#<STANDARD-CLASS DOCPARSER:CONDITION-NODE>
#<STANDARD-CLASS DOCPARSER:CONDITION-NODE>
#<STANDARD-CLASS DOCPARSER:CONDITION-NODE>
In package: YAML.FLOAT.
#<STANDARD-CLASS DOCPARSER:VARIABLE-NODE>
#<STANDARD-CLASS DOCPARSER:VARIABLE-NODE>
#<STANDARD-CLASS DOCPARSER:FUNCTION-NODE>
#<STANDARD-CLASS DOCPARSER:FUNCTION-NODE>
#<STANDARD-CLASS DOCPARSER:FUNCTION-NODE>
...
“‘
## Extending
You can extend docparser in two ways: Adding new parsers and new classes. Adding
new classes probably won’t be very useful unless you also modify the client of
your extension to use them. Adding new parsers that instantiate existing
documentation classes, however, can be very useful.
For instance, you could have a parser that extracts information from a custom
‘defwidget‘ macro in a GUI framework, and creates an instance of ‘class-node‘
with a modified docstring.
Alternatively, if you’re writing a documentation generator specific to this
framework, you could create a subclass of ‘class-node‘, ‘widget-node‘, with
extra slots for the added information.
To define a new parser, use the ‘define-parser‘ macro. As an example of use,
this is the definition of the parser for ‘defmacro‘ forms:
“‘lisp
(define-parser cl:defmacro (name (&rest args) &rest body)
(let ((docstring (if (stringp (first body))
(first body)
nil)))
(make-instance ’macro-node
:name name
:docstring docstring
:lambda-list args)))
“‘
# License
Copyright (c) 2015 Fernando Borretti
Licensed under the MIT License.
0.1
trivial-types (system).
alexandria (system).
anaphora (system).
cffi (system).
src (module).
Modules are listed depth-first from the system components tree.
docparser/srcdocparser (system).
package.lisp (file).
nodes.lisp (file).
equal.lisp (file).
core.lisp (file).
parsers.lisp (file).
print.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
docparser/docparser.asddocparser/src/package.lispdocparser/src/nodes.lispdocparser/src/equal.lispdocparser/src/core.lispdocparser/src/parsers.lispdocparser/src/print.lispdocparser/src/nodes.lisppackage.lisp (file).
src (module).
cffi-bitfield (class).
cffi-bitfield-masks (reader method).
cffi-enum (class).
cffi-enum-variants (reader method).
cffi-function (class).
cffi-function-foreign-name (reader method).
cffi-function-return-type (reader method).
cffi-node (class).
cffi-slot (class).
cffi-slot-type (reader method).
cffi-struct (class).
cffi-struct-slots (reader method).
cffi-type (class).
cffi-type-base-type (reader method).
cffi-union (class).
cffi-union-variants (reader method).
class-node (class).
class-node-default-initargs (reader method).
class-node-metaclass (reader method).
class-node-superclasses (reader method).
class-slot-node (class).
condition-node (class).
documentation-node (class).
function-node (class).
generic-function-node (class).
macro-node (class).
method-node (class).
method-qualifiers (reader method).
name-node (class).
node (class).
node-docstring (reader method).
node-form (reader method).
(setf node-form) (writer method).
node-name (reader method).
operator-lambda-list (reader method).
operator-node (class).
operator-setf-p (reader method).
record-node (class).
record-slots (reader method).
record-slots (reader method).
render-humanize (function).
slot-accessors (reader method).
slot-allocation (reader method).
slot-initarg (reader method).
slot-initform (function).
slot-readers (reader method).
slot-type (reader method).
slot-writers (reader method).
struct-node (class).
struct-node-conc-name (reader method).
struct-node-constructor (reader method).
struct-node-copier (reader method).
struct-node-include-name (reader method).
struct-node-include-slots (reader method).
struct-node-initial-offset (reader method).
struct-node-named (reader method).
struct-node-predicate (reader method).
struct-node-print-function (reader method).
struct-node-print-object (reader method).
struct-node-type (reader method).
struct-slot-accessor (reader method).
struct-slot-node (class).
struct-slot-read-only (reader method).
struct-slot-type (reader method).
symbol-external-p (function).
symbol-package-name (function).
type-node (class).
variable-initial-value (reader method).
variable-node (class).
docparser/src/equal.lispnodes.lisp (file).
src (module).
node= (generic function).
define-equality (macro).
slot-or-nil (function).
docparser/src/core.lispequal.lisp (file).
src (module).
*store-form* (special variable).
define-parser (macro).
do-nodes (macro).
do-packages (macro).
index (class).
package-index (class).
package-index-docstring (reader method).
package-index-name (reader method).
parse (function).
query (function).
*parsers* (special variable).
add-node (function).
add-package-index (function).
ensure-preload (function).
find-nodes (function).
find-package-index (function).
index-packages (reader method).
(setf index-packages) (writer method).
load-system (function).
node-exists-p (function).
package-index-nodes (reader method).
(setf package-index-nodes) (writer method).
parse-form (function).
parse-package-definition (function).
parse-system (function).
with-ignored-errors (macro).
docparser/src/parsers.lispcore.lisp (file).
src (module).
extract-docstring (function).
parse-cffi-slot (function).
parse-slot (function).
parse-struct-slot (function).
parse-var (function).
docparser/src/print.lispparsers.lisp (file).
src (module).
dump (function).
print-object (method).
print-object (method).
print-object (method).
print-object (method).
print-object (method).
print-object (method).
print-object (method).
print-object (method).
print-object (method).
print-object (method).
print-object (method).
Packages are listed by definition order.
docparserParse documentation from ASDF systems.
common-lisp.
*store-form* (special variable).
cffi-bitfield (class).
cffi-bitfield-masks (generic reader).
cffi-enum (class).
cffi-enum-variants (generic reader).
cffi-function (class).
cffi-function-foreign-name (generic reader).
cffi-function-return-type (generic reader).
cffi-node (class).
cffi-slot (class).
cffi-slot-type (generic reader).
cffi-struct (class).
cffi-struct-slots (generic reader).
cffi-type (class).
cffi-type-base-type (generic reader).
cffi-union (class).
cffi-union-variants (generic reader).
class-node (class).
class-node-default-initargs (generic reader).
class-node-metaclass (generic reader).
class-node-superclasses (generic reader).
class-slot-node (class).
condition-node (class).
define-parser (macro).
do-nodes (macro).
do-packages (macro).
documentation-node (class).
dump (function).
extract-docstring (function).
function-node (class).
generic-function-node (class).
index (class).
macro-node (class).
method-node (class).
name-node (class).
node (class).
node-docstring (generic reader).
node-form (generic reader).
(setf node-form) (generic writer).
node-name (generic reader).
node= (generic function).
operator-lambda-list (generic reader).
operator-node (class).
operator-setf-p (generic reader).
package-index (class).
package-index-docstring (generic reader).
package-index-name (generic reader).
parse (function).
query (function).
record-node (class).
record-slots (generic reader).
render-humanize (function).
slot-accessors (generic reader).
slot-allocation (generic reader).
slot-initarg (generic reader).
slot-initform (function).
slot-readers (generic reader).
slot-type (generic reader).
slot-writers (generic reader).
struct-node (class).
struct-node-conc-name (generic reader).
struct-node-constructor (generic reader).
struct-node-copier (generic reader).
struct-node-include-name (generic reader).
struct-node-include-slots (generic reader).
struct-node-initial-offset (generic reader).
struct-node-named (generic reader).
struct-node-predicate (generic reader).
struct-node-print-function (generic reader).
struct-node-print-object (generic reader).
struct-node-type (generic reader).
struct-slot-accessor (generic reader).
struct-slot-node (class).
struct-slot-read-only (generic reader).
struct-slot-type (generic reader).
symbol-external-p (function).
symbol-package-name (function).
type-node (class).
variable-initial-value (generic reader).
variable-node (class).
*parsers* (special variable).
add-node (function).
add-package-index (function).
define-equality (macro).
ensure-preload (function).
find-nodes (function).
find-package-index (function).
index-packages (generic reader).
(setf index-packages) (generic writer).
load-system (function).
node-exists-p (function).
package-index-nodes (generic reader).
(setf package-index-nodes) (generic writer).
parse-cffi-slot (function).
parse-form (function).
parse-package-definition (function).
parse-slot (function).
parse-struct-slot (function).
parse-system (function).
parse-var (function).
slot-or-nil (function).
with-ignored-errors (macro).
Definitions are sorted by export status, category, package, and then by lexicographic order.
Whether or not to store, inside a node, the form it was parsed from.
Define a parser.
Iterate over every node in a package index.
Iterate over every package in the index.
Print a tree of the contents of an index to the *standard-output*.
Extract the docstring from the body of a form.
Correctly handles bodies where the first form is a declaration.
Parse documentation from either a system name or a list of system names.
Find all documentation nodes in the index matching the constraints and returns them as a vector. package-name and symbol-name are strings, class is the symbol of a class name. If none are found, return NIL.
Render a symbol into a string in a human-friendly way.
Return the initform for the slot.
Also returns a second boolean value indicating whether the slot has an initform,
so an initform of NIL can be distinguished from not having an initform at all.
Whether or not a symbol is external.
Return the name of a package’s symbol.
cffi-bitfield)) ¶A list of masks (keywords).
cffi-function)) ¶The function’s foreign name.
cffi-function)) ¶The function’s return type.
cffi-struct)) ¶A list of CFFI slots.
cffi-union)) ¶A list of CFFI slots.
class-node)) ¶The class’s metaclass (symbol).
class-node)) ¶The class’s metaclass (symbol).
class-node)) ¶A list of the class’s superclasses (symbols).
documentation-node)) ¶The node’s documentation.
Test whether a and b are equal.
cffi-bitfield) (b cffi-bitfield)) ¶cffi-union) (b cffi-union)) ¶cffi-struct) (b cffi-struct)) ¶cffi-function) (b cffi-function)) ¶class-node) (b class-node)) ¶struct-node) (b struct-node)) ¶class-slot-node) (b class-slot-node)) ¶struct-slot-node) (b struct-slot-node)) ¶method-node) (b method-node)) ¶generic-function-node) (b generic-function-node)) ¶function-node) (b function-node)) ¶operator-node) (b operator-node)) ¶documentation-node) (b documentation-node)) ¶The default method.
operator-node)) ¶The operator’s lambda list.
operator-node)) ¶Whether the operator is a setf operation.
package-index)) ¶The package’s docstring.
package-index)) ¶The package’s name.
class-node)) ¶A list of slots.
struct-node)) ¶A list of slots.
class-slot-node)) ¶automatically generated reader method
class-slot-node)) ¶The slot’s allocation type.
class-slot-node)) ¶The slot’s initarg.
class-slot-node)) ¶automatically generated reader method
class-slot-node)) ¶The slot’s type.
type.
class-slot-node)) ¶automatically generated reader method
struct-node)) ¶The prefix used for the struct’s slot accessors.
struct-node)) ¶The constructor; which is nil if there is none, the
constructor’s symbol, or a list of the boa-constructor’s
symbol and arguments.
struct-node)) ¶The copier function.
struct-node)) ¶Structure that this one inherits from, if any.
struct-node)) ¶Included structure slot descriptions.
struct-node)) ¶The structure’s initial offset (integer), or nil if :type was not given.
struct-node)) ¶Whether the structure is named or not.
struct-node)) ¶The predicate function.
struct-node)) ¶The print-function function, or nil if there is none.
struct-node)) ¶The print-object function, or nil if there is none.
struct-node)) ¶The structure’s representation.
type.
struct-slot-node)) ¶The slot’s accessor.
struct-slot-node)) ¶Whether the slot is readonly or not.
struct-slot-node)) ¶The slot’s type.
type.
variable-node)) ¶automatically generated reader method
method-node)) ¶automatically generated reader method
condition-node) stream) ¶Print a condition definition node.
cffi-function) stream) ¶struct-node) stream) ¶Print a struct definition node.
class-node) stream) ¶Print a class definition node.
cffi-union) stream) ¶operator-node) stream) ¶Print an operator node.
cffi-struct) stream) ¶variable-node) stream) ¶Print a variable node.
A C bitfield.
A list of masks (keywords).
(trivial-types:proper-list keyword)
:masks
This slot is read-only.
A C enum.
A list of enum values (keywords).
(trivial-types:proper-list keyword)
:variants
This slot is read-only.
A C function.
The base class of all CFFI documentation nodes. Does not
inherit from documentation-node as not all sub-nodes have docstrings.
A struct or union slot.
The slot’s type.
common-lisp.
:type
This slot is read-only.
A C structure.
A list of CFFI slots.
(trivial-types:proper-list docparser:cffi-slot)
:slots
This slot is read-only.
A C type.
The type’s base type.
:base-type
This slot is read-only.
A C union.
A list of CFFI slots.
(trivial-types:proper-list docparser:cffi-slot)
:variants
This slot is read-only.
A class.
A list of the class’s superclasses (symbols).
(trivial-types:proper-list symbol)
:superclasses
This slot is read-only.
The class’s metaclass (symbol).
symbol
:metaclass
This slot is read-only.
The class’s metaclass (symbol).
(trivial-types:proper-list)
:default-initargs
This slot is read-only.
A list of slots.
(trivial-types:proper-list docparser:class-slot-node)
:slots
This slot is read-only.
A class or structure slot.
(trivial-types:proper-list symbol)
:accessors
This slot is read-only.
(trivial-types:proper-list symbol)
:readers
This slot is read-only.
(trivial-types:proper-list symbol)
:writers
This slot is read-only.
The slot’s type.
common-lisp.
:type
This slot is read-only.
The slot’s initarg.
:initarg
This slot is read-only.
The slot’s initform.
:initform
The slot’s allocation type.
keyword
:instance
:allocation
This slot is read-only.
A condition.
The base class of all documentable nodes.
The node’s documentation.
(or null string)
:docstring
This slot is read-only.
A function.
A generic function.
Holds system documentation, and the internal package indices.
A vector of package indices.
(vector docparser:package-index)
(make-array 0 :adjustable t :element-type (quote docparser:package-index) :fill-pointer 0)
A macro.
A method.
:qualifiers
This slot is read-only.
The base class of nodes with symbol names.
The base class of all nodes.
The base class of functions and macros.
The operator’s lambda list.
:lambda-list
This slot is read-only.
Whether the operator is a setf operation.
boolean
:setfp
This slot is read-only.
Holds the documented objects in this package.
The package’s name.
string
:name
This slot is read-only.
The package’s docstring.
(or null string)
:docstring
This slot is read-only.
A vector of documentation objects.
(vector docparser:documentation-node)
(make-array 0 :adjustable t :element-type (quote docparser:documentation-node) :fill-pointer 0)
The base class of all nodes representing record-like data type definitions (i.e. structures, classes).
A structure.
A list of slots.
(trivial-types:proper-list docparser:struct-slot-node)
:slots
This slot is read-only.
The prefix used for the struct’s slot accessors.
string
:conc-name
This slot is read-only.
The constructor; which is nil if there is none, the
constructor’s symbol, or a list of the boa-constructor’s
symbol and arguments.
(or symbol trivial-types:proper-list)
:constructor
This slot is read-only.
The copier function.
symbol
:copier
This slot is read-only.
Structure that this one inherits from, if any.
symbol
:include-name
This slot is read-only.
Included structure slot descriptions.
(trivial-types:proper-list docparser:struct-slot-node)
:include-slots
This slot is read-only.
The structure’s initial offset (integer), or nil if :type was not given.
(or null (integer 0))
:initial-offset
This slot is read-only.
Whether the structure is named or not.
boolean
:named
This slot is read-only.
The predicate function.
symbol
:predicate
This slot is read-only.
The print-function function, or nil if there is none.
symbol
:print-function
This slot is read-only.
The print-object function, or nil if there is none.
common-lisp.
symbol
:print-object
This slot is read-only.
The structure’s representation.
common-lisp.
(or null symbol (cons symbol (cons (or symbol list) null)))
:type
This slot is read-only.
A structure’s slot.
The slot’s initform.
:initform
The slot’s type.
common-lisp.
t
:type
This slot is read-only.
Whether the slot is readonly or not.
boolean
:read-only
This slot is read-only.
The slot’s accessor.
symbol
:accessor
This slot is read-only.
A type.
A variable.
:initial-value
This slot is read-only.
A list of symbols to the functions used to parse their corresponding forms.
Catch and ignore certain errors.
Add a node to an index, finding the proper package index.
Return a vector of nodes satisfying node-predicate, in packages satisfying package-predicate.
Return the package-index with that name, or NIL.
Load an ASDF system by name.
Does the node exist in the package index.
package-index)) ¶package-index)) ¶A vector of documentation objects.
| Jump to: | (
A C D E F G I L M N O P Q R S V W |
|---|
| Jump to: | (
A C D E F G I L M N O P Q R S V W |
|---|
| Jump to: | *
A B C D F I L M N P Q R S T V W |
|---|
| Jump to: | *
A B C D F I L M N P Q R S T V W |
|---|
| Jump to: | C D E F G I M N O P R S T V |
|---|
| Jump to: | C D E F G I M N O P R S T V |
|---|