Incremental redocumentation using literate programming

The primary aim of this research is to investigate means of improving program comprehension through redocumentation. In particular it will concentrate on using Literate Programming as a method for program redocumentation. Documentation is crucially important as an aid to understanding software systems. The Incremental Redocumentation Using Literate Programming System analyses the existing source code and merges in a range of other information, in order to create a complete documentation package. This may include not only traditional paper documents, but also hypertext facilities, animated specifications and output from other analysis tools. The status of the documentation is implicitly elevated to that of an integral part of the system, rather than an optional extra. Where a configuration management system is used to manage different versions of a system, the documentation can also be brought under its control. The literate programming paradigm provides the encouragement and capability to produce high quality code and documentation simultaneously. Conceptually, literate programming systems are document preparation systems. The primary goal of a literate program is to be understandable to the programmers who are going to have to read it at some later date - often while involved in maintenance, or perhaps when trying to determine the possibility of reusing parts of the code for later projects. This thesis presents a structures of C programs and literate C programs, and describes the features of captured literate C programs. A method of the capture process and also the functions of the redocumentation process are described. In addition, this thesis outlines how the individual stages in the capture process and the edit process are used to redocument a C program. The results of application of the process are highlighted by way of example programs. The evaluation process is performed by comparing the results of an existing literate program with those resulting from the application of the method described within this thesis. The results have shown that the captured redocumented literate C program is more readable and understandable than source code only, and that it provides a basis for subsequent maintenance and further redocumentation

AOPS : an abstraction oriented programming system for literate programming

The practice of literate programming is not widespread because existing literate programming systems have some undesirable characteristics such as programming language and text processor dependence and lack of flexible tools for viewing and manipulation of the source file. This dissertation describes the literate programming system AOPS (Abstraction Oriented Programming System) which addresses both of these problems. AOPS is programming language and text processor independent literate programming system. AOPS tools include a hypertext browser, a lister with the ability to select what is presented and what is suppressed, and a filter to extract the program code from the AOPS source file. AOPS introduces the notion of a phantom abstraction that enhances the understandability of the literate program and when used in conjunction with the browser greatly extends the capabilities of AOPS. We also discuss how the design of AOPS supports extension of the concept of literate programming to encompass the entire software life cycle. Finally we describe an experiment which showed that literate programs contain more documentation than traditional programs

Industrial-Strength Documentation for ACL2

The ACL2 theorem prover is a complex system. Its libraries are vast. Industrial verification efforts may extend this base with hundreds of thousands of lines of additional modeling tools, specifications, and proof scripts. High quality documentation is vital for teams that are working together on projects of this scale. We have developed XDOC, a flexible, scalable documentation tool for ACL2 that can incorporate the documentation for ACL2 itself, the Community Books, and an organization's internal formal verification projects, and which has many features that help to keep the resulting manuals up to date. Using this tool, we have produced a comprehensive, publicly available ACL2+Books Manual that brings better documentation to all ACL2 users. We have also developed an extended manual for use within Centaur Technology that extends the public manual to cover Centaur's internal books. We expect that other organizations using ACL2 will wish to develop similarly extended manuals.Comment: In Proceedings ACL2 2014, arXiv:1406.123