Larceny Note #12: Procedure Documentation

Lars T Hansen / 25 November 1998

Introduction

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

Procedure-name: a symbol.
Procedure-expression: a datum representing the source code.
Arity: a nonnegative integer. If exact, then the procedure takes exactly that many arguments. If inexact, then the procedure takes at least that many arguments.
File-name: a string denoting the originating file.
File-position: an exact integer denoting the position of the source code for the procedure within the file. If this field has the value k, then k characters precede the opening parenthesis of the source code.

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 $
larceny@ccs.neu.edu