A source code documentation system for Ada
Yingjie Wu, Theodore P. Baker · ACM SIGAda Ada Letters · 1989
4 1 .Introduction .This paper presents a first step toward a high-quality source code documentation syste m for Ada .The system is an adaptation of Web 2 , a system of structured documentation created as a part o f the TEX project by Professor Donald E .Knuth [1-3] at Stanford University .The chief virtues of the Web system are that it encourages consistency between code and documentatio n and it supports the production of high-quality typeset documentation in a uniform style .With Web th e source code and documentation of a program are combined in a single file .There are two programs, Weav e and Tangle, which produce Tl typesetting commands and compilable source code, respectively, from th e Web file .Since Tangle automatically organizes the code fragments into a compilable order as it extract s them from the Web file, the author is freed of syntactic constraints imposed by the programming language , and can structure the Web file in a way that makes the final typeset documentation most readable .Anyon e who has attempted to typeset computer program code manually and maintain consistency between sourc e code and typeset documentation for succesive versions of a program will readily appreciate these virtues .Since Web was designed specifically to support only Pascal programs, it needed adaptation to support Ada .Y .C .Wu has produced such an adaptation, called A-Web .The A-Web system is comprised of two programs , A-Weave and A-Tangle .These perform functions analogous to Knuth's original Weave and Tangle, but fo r Ada programs .The program A-Weave is an adaptation of the original Weave, written in Pascal .The components specifi c to the Pascal syntax were recoded to support the Ada syntax .In contrast, A-Tangle is written in Ada, an d is a new design .The original Tangle puts the extracted source code out in a compressed (difficult to read ) form, whereas A-Tangle indents its output neatly .A--Tangle is based on a decision table, which specifie s output formatting actions to be taken for various Ada tokens .The context-sensitive grammar scheme use d in Knuth's original system was difficult to modify, due to interactions between the rules .The decision tabl e makes tuning the output format easier, through local adjustments .A-Weave was written using Web, an d A-Tangle was written using A-Web .This paper is an example of A-Web documentation .It was written in A-Web, and processed by A-Weave .The following sections show how the A-Web system can be used to document an Ada package, illustratin g the typeset output, the Web code, and the outputs of A-Weave and A-Tangle .The final section summarize s A-Web's strengths and weaknesses, and points out the direction in which we plan to continue toward a high-quality source-code documentation system for Ada .