Code-Browser Utility

Code-Browser Utility
SchemeStation documentation

1 Introduction

One of the main aspects of the SCHEMESTATION project is the understability of the system. The quality of the documentation is essential to ensure that the further development of the system can take place after this project. Documentation will be made in a special html-like ssdoc-format, that is automatically converted into html-format. The purpose of this convention is to make documentation easier; the visual appearance of the documents is made automatically by the conversion script.

Further documentation of the documentation system can be found in .

To make code browsing easier, a web-based code-browser (in url http://schemestation.cs.hut.fi/cgi-bin/code-browser/status.pl?index=1) will be developed as a side-effect of this project. The aim is to make finding functions and their headers, searching code and getting oversight to the system for both the members of the project and the outsiders.

2 Overview

The utility will recursively travel the filesystem beginning from given root(s). It will parse the C header files and scheme files found in the sub-directories. The function definitions and data structures (not implemented yet) will be in code-browser's internal index along with the descriptions found in comments.

The source can then be searched using regular expression to specify the search key. The entire code can be sought, but the search can also be limited to match function names or file names.

The search result will so the matching functions and their return values, arguments and descriptions on request. (Example: without details and in detail).

The code can be browsed with a web-browser - the code-browser fontifies the code and make links from include directives and function names to the correspondent documents.

3 Requirements

The browser recognizes standard C (ansi) and scheme syntax so that it can find the function definitions and data structures. The code must be under certain root-director{y,ies} so that it can be found during the file traversal. To make it possible to find the function descriptions, they have to placed in a comment straight before the definition of the function both in scheme files and C header files.

The browser is implemented in perl. Perl has to be available during both index contruction and code searching/browsing. The user interface is web-based and the searching/brwosing scripts are ran as cgi-programs, so http-server capable of using cgi-programs is needed.

4 Automagical documentation

It is possible to embed the code-browser -generated function and data-structure descriptions in builddocs (descibed in Documentation) generated documentation. The browser formats an entry of each function in the specified place in the document.