Larceny Note #12: Procedure Documentation

Lars T Hansen / 25 November 1998


Compiled and interpreted code contains procedure documentation to aid in debugging. This note documents the layout and location of the procedure documentation.

Documentation Layout

A procedure documentation datum is a vector; vectors are nice because they are extensible. The vector contains the following fields, in order. Any field can have the value #f, meaning "no information available".

Accessing the data

Procedure documentation data are most conveniently accessed with the procedure information accessors.

Additionally, the undocumented procedure procedure-documentation can be used to retrieve documentation from a procedure:

(procedure-documentation proc) => doc
(procedure-documentation proc offset) => doc

Returns procedure documentation for the procedure proc. If no documentation is available, returns #f. The first form is equivalent to the second form with offset=0.

If offset is supplied, then it must specify a valid instruction address in the procedure's code vector, and the documentation structure returned, if any, is the one appropriate for the given instruction.

Procedure Layout

The documentation slot is always slot 0 in the constant vector of a procedure. Three values are legal for the documentation slot. If the value is #f, then no information is available. If the value is a vector, then that vector is the procedure documentation. If the value is a list, then it must be a list of pairs. The pairs contain procedure information for instruction-address ranges. The car of a pair is a nonnegative exact fixnum: it is the first address for which the documentation structure in the cdr is valid. The list is sorted on the car of the pair.

The assembler sets up the procedure documentation structures from information supplied by the compiler. The interface between the compiler and assembler is insufficiently documented.

$Id: note12-procinfo.html 89 1998-11-25 14:46:38Z lth $