4.5 Documentation, testing, and demos

Common Lisp offers several interesting possibilities for integrating the documentation and testing phase with programming in a way which cannot easily be done in languages that are not interactive or do not have sufficient introspection features. FEMLISP uses such features as follows:

First, function and variable declarations may contain docstrings documenting their use. These strings can be asked for in the interactive environment. In FEMLISP, those strings are also used to extract a reference manual in Texinfo format (Texinfo is the documentation language of the GNU project), see Reference manual. Therefore, Texinfo formatting commands are allowed in Femlisp docstrings.

Second, regression test suites can be constructed easily. For example, most files in FEMLISP contain a test function at the end which checks several critical features which the file or module provides. By calling the function adjoin-test at load time, this function is added to a list of functions to be checked. After loading FEMLISP, all functions in this list can be executed one after the other by calling the function test-femlisp. Errors and exceptions are registered and finally reported.

Third, a demo suite is also built FEMLISP in a similarly distributed manner. Wherever something interesting can be demonstrated, a small demo node is generated with make-demo and added to the tree of all demos with adjoin-demo. After loading FEMLISP, the whole demo suite is available and can be run with the command femlisp-demo.