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.0.0, generated automatically by Declt version 2.3 "Robert April" on Tue Jan 09 14:29:44 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.


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

list-symbols (function)


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

list-symbols (function)


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 docstring. In the many argument structure the first argument is the
type, the last is the docstring, 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 (DOCUMENTATION SPECIFIER TYPE).

See *DOCUMENTATION-TRANSLATORS*

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)


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)


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

5.2 Internal definitions


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

5.2.1 Functions

Function: list-symbols PACKAGE &key INTERNAL
Package

documentation-utils

Source

toolkit.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.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   L   M   R  
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
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

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

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

Jump to:   (  
C   D   F   L   M   R  

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:   D   P   S  
Index Entry  Section

D
documentation-utils: The documentation-utils system
documentation-utils: The documentation-utils package

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

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

Jump to:   D   P   S