Documentation Paradigms - A Progres Report
Mr. Michal Iglewski
Dr. Jan Madey
Dr. David Lorge Parnas
Mr. Philip Kelly
Software Engineering Research Group
CRL, McMaster University,
Hamilton, Ontario, Canada L8S 4K1
This paper illustrates two of the computer systems documents discussed in . A module interface
specification treats the module as a black-box, identifying all module's access-programs (i.e. programs
that can be invoked from outside the module), and describing their externally visible effects. The interface
is documented by the trace assertion method . A module internal design document, one for each
implementation of the module, describes the module's (internal) data structure, the intended interpretation
of that data structure (in terms of the module interface), and the effect of each access-program on the
module's data structure. Program effect is described by a mapping from a set of data states before program
execution to a set of data states after program execution. This mapping is expressed by LD-relations [7,13].
We illustrate these documents by presenting a few modules which were specified, designed, implemented, and tested within the Table Tool Project .
The paper contains also a sample implementation of these modules based on the module internal
design document. The accompanying paper  describes the way this implementation was tested against
the module interface specification.