Package Documentation for Corman Lisp

Note: Applies to Corman Lisp versions > 3.01 running under Windows XP or Vista. The current release of Corman Lisp (version 3.01) needs some patching to work with :document-package. When the next release of Corman Lisp happens, I will update things as needed; until then, if you have an urgent need for a package documentation library under Corman Lisp you may contact me at g n e i l .at. L i b e r t y R e a c h . c o m and I will send you the necessary patches.

Document-Package – a package for documenting packages in Corman Lisp

I am releasing a utility for documenting a lisp package — unsurprisingly called :document-package.  It is a brain-dead cousin to the familiar doxygen utility.  The major difference is that, in lisp, it is possible and considered good practice to include documentation strings as part of the definition of your lisp objects as you create them.  Thus, a properly-written lisp library should be self-documenting.

The :document-package package steps through all exported and local objects in a package, extracts their documentation strings and other information such as associated lambda-lists, types, etc., and displays it all in a legible format.  It is possible to produce package documentation as plain text or as formatted html.

You can download the source for the package from here.  There is a document-package.system file included in the distribution if you prefer to load via mk:defsystem.  There is also a load-me.lisp file if you wish to simply load a file to get the package.  In any event, (use-package :dp) will make the package available.  You can test the package by running it on itself via (document :dp).

The following documentation was produced by running (document :dp :html t).

Documentation for Package DOCUMENT-PACKAGE

Nicknames:

• DP

 

Package Uses:

• COMMON-LISP

 

The :document-package package defines several useful documentation functions for use with Corman

Common Lisp v3.02+. It is meant to help in collating and writing documentation for lisp packages.

The way to use this package is as follows (in order of importance):

1. Document your package by placing a nice informative documentation string in the defpackage

declaration. Like this one!

2. Document each of your exported functions. Ideally including preconditions, semantics, side

effects, error conditions, and return values for each function.

3. Document each of your exported variables. Describe their semantics and legal values.

4. Document each of your local functions at least by describing the semantics.

Run the function (document ‘package-name). All the documentation will be

collected and displayed.

To test this package:

1. Un-block-comment the series of definitions at the end of the document-package.lisp file.

2. Reload the document-package package.

3. Run document-package on itself via (dp:document :dp) or (dp:document ‘DP) or

(dp:document “DOCUMENT-PACKAGE”) — they should all work by printing documentation to stdout.

Author: Neil Haven

Contact: [DELETED]

Release Version: 1.0.0 [May 2008]

Legal Restrictions on Use: GNU LGPL

Symbols Exported from DOCUMENT-PACKAGE

DOCUMENT [FUNCTION]

Usage: (DOCUMENT PACKAGE &KEY (STREAM *STANDARD-OUTPUT*) (HTML NIL))

Syntax: (document package :stream stream :html flag)

Arguments: /package/ is a package designator. The output /stream/ defaults to *standard-output*.

/html/ defaults to nil.

Preconditions: /package/ is loaded.

Semantics: collect and print all documentation for /package/ onto the output /stream/. If

/html/ is t, then the documentation is formatted as html.

Side Effects:

Error Conditions: /package/ must be loaded

Returns: t on success, nil on failure.

Symbols Internal to DOCUMENT-PACKAGE

FORMAT-H2 [MACRO]

Usage: (FORMAT-H2 STREAM FMT &REST ARGS)

Creates an header2 element

DOCUMENT-TYPE-BINDING [FUNCTION]

Usage: (DOCUMENT-TYPE-BINDING SYM &OPTIONAL (STREAM *STANDARD-OUTPUT*))

documentation for a type from deftype

FORMAT-H1 [MACRO]

Usage: (FORMAT-H1 STREAM FMT &REST ARGS)

Centers a header1 element

FORMAT-TITLED-LIST [MACRO]

Usage: (FORMAT-TITLED-LIST STREAM TITLE LIST)

==> title: a, b, c

NOPKG [FUNCTION]

Usage: (NOPKG STREAM ARGUMENT COLON ATSIGN &REST X)

a callable print function to ignore package designators in output

DOCUMENT-STRUCT-BINDING [FUNCTION]

Usage: (DOCUMENT-STRUCT-BINDING SYM &OPTIONAL (STREAM *STANDARD-OUTPUT*))

documentation for a structure from defstruct

FIND-DOC-STRING [FUNCTION]

Usage: (FIND-DOC-STRING BODY)

searches for a documentation string in a method body

DOCUMENT-SYMBOL-MACRO [FUNCTION]

Usage: (DOCUMENT-SYMBOL-MACRO SYM &OPTIONAL (STREAM *STANDARD-OUTPUT*))

documentation for a symbol macro

DOCUMENT-FUNCTION-BINDING [FUNCTION]

Usage: (DOCUMENT-FUNCTION-BINDING SYM &OPTIONAL (STREAM *STANDARD-OUTPUT*))

dispatch depending on function type; defmacro, defun, defgeneric, define-modify-macro

FORMAT-HTML-HEADER [MACRO]

Usage: (FORMAT-HTML-HEADER STREAM TITLE)

Create a html header with a title

DOCUMENT-SETF [FUNCTION]

Usage: (DOCUMENT-SETF SYM &OPTIONAL (STREAM *STANDARD-OUTPUT*))

documentation for defsetf

DOCUMENT-SETF-EXPANDER [FUNCTION]

Usage: (DOCUMENT-SETF-EXPANDER SYM &OPTIONAL (STREAM *STANDARD-OUTPUT*))

documentation for define-setf-expander

DOCUMENT-METHOD-FUNCTION [FUNCTION]

Usage: (DOCUMENT-METHOD-FUNCTION METHOD &OPTIONAL (STREAM *STANDARD-OUTPUT*))

documentation for standard method functions from defmethod

REFORMAT-TEXT-FOR-HTML [MACRO]

Usage: (REFORMAT-TEXT-FOR-HTML TEXT)

==> text

DOCUMENT-STANDARD-FUNCTION [FUNCTION]

Usage: (DOCUMENT-STANDARD-FUNCTION SYM &OPTIONAL (STREAM *STANDARD-OUTPUT*))

documentation for a function from defun

DOCUMENT-CLASS-BINDING [FUNCTION]

Usage: (DOCUMENT-CLASS-BINDING SYM &OPTIONAL (STREAM *STANDARD-OUTPUT*))

documentation for a class from defclass

*HTML-VERSION* [SYMBOL]: T

set to t for output formatted as html, nil otherwise

FORMAT-HTML-FOOTER [MACRO]

Usage: (FORMAT-HTML-FOOTER STREAM)

Create a html footer

DOCUMENT-MACRO-FUNCTION [FUNCTION]

Usage: (DOCUMENT-MACRO-FUNCTION SYM &OPTIONAL (STREAM *STANDARD-OUTPUT*))

documentation for a macro from defmacro and define-modify-macro

DOCUMENT-GENERIC-FUNCTION [FUNCTION]

Usage: (DOCUMENT-GENERIC-FUNCTION SYM &OPTIONAL (STREAM *STANDARD-OUTPUT*))

documentation for a generic function from defgeneric

DOCUMENT-VARIABLE-BINDING [FUNCTION]

Usage: (DOCUMENT-VARIABLE-BINDING SYM &OPTIONAL (STREAM *STANDARD-OUTPUT*))

documentation for a special variable via defvar defparameter defconstant

PRINT-DOCUMENTATION [FUNCTION]

Usage: (PRINT-DOCUMENTATION VAR &OPTIONAL (STREAM *STANDARD-OUTPUT*))

print documentation for var on stream

DOCUMENT-COMPILER-MACRO-FUNCTION [FUNCTION]

Usage: (DOCUMENT-COMPILER-MACRO-FUNCTION SYM &OPTIONAL (STREAM *STANDARD-OUTPUT*))

documentation for a compiler macro from define-compiler-macro

BREAK-TEXT [FUNCTION]

Usage: (BREAK-TEXT TEXT)

substitutes [br/]
~% for all occurrences of
~% and #newline in text