[file:///protected/general/Header.html]
Overview
Rationale for development
Design solutions
Implementation
User Guide
Example Output
Points of contact
This page presents CGull, an application for automatically extracting documentation from C++ code and presenting it in an HTML format. It covers the rationale for developing CGull, the functionality it provides and the method of implementation.
CGull is a utility program that is developed in Perl 5 to run on the UNIX platform. It allows its users to automatically generate technical documentation, in HTML format, directly from their C++ source code. CGull allows users to produce regular updates of the their software documentation for publication on a Web server in line with releases of their software, perhaps on an FTP server.
CGull produces documentation by interpreting the C++ statements and corresponding comments provided in the latest source code: both header files and body files. The resulting documentation includes automatically generated hypertext links that provide cross-referencing between key programming concepts such as classes, structures, methods and enumerated types. It contains details of when the documentation was compiled and gives instructions on where to find the latest versions of the software.
A unique feature of CGull is the ability to generate well formatted, professional looking, documents from standard source code. There is no need for the programmer to adopt a clumsy programming style or to incorporate HTML tags within the C++ comments. CGull relies simply on the fact that comments describing code items should appear directly above those code items. An important goal of the CGull utility was that the C++ source code required as input should look like standard C++, whilst the resulting documentation should look like a well produced, polished product.
CGull takes as input a list of C++ files, both header and body. It produces from this an HTML index page - labelled with the date it was created and listing the name of each class found - and then one page for each file which contained a class. The class descriptions are broken down into:
By default CGull separates out information about the private interface of the class and stores it in another file accessed by a hypertext link from the main file.
CGull has additional features allowing the user to insert pictures in to their documentation and to specify certain formats such as bold, italic, pre-formatted, bullet points and numbered lists.
One feature that makes CGull very versatile is its method of finding the comments for member functions. To work with the GRACE C++ coding standards CGull looks first in the implementation file for the class, but if no comments are found there CGull will look in the header file. This means that projects with different coding standards to GRACE, who comment their classes solely in the header file can still use CGull. CGull does not need to view the implementation files
Hence, although CGull is intended to address a requirement of CABLE its use should prove applicable within all GRACE work-packages and on other C++ projects.
A large amount of C++ code exists on the GRACE project which needs to be documented in a format accessible to everyone in the consortium. In the case of Cable, detailed comments are interspersed within the source code, providing adequate documentation for programmers - at least once they know where to look for it. A more accessible form of documentation is required for the users of CABLE, but the C++ comments remain a valuable source of information for producing this documentation.
The World Wide Web (WWW) is a very effective way of presenting up to date information on a changing subject to a wide community of users. The Web is ideal for presenting users with the most current version of software documentation. By producing documentation in HTML format, and setting it up as a Web page, all the members of the GRACE consortium can have access to it. The use of HTML also allows the insertion of hypertext links allowing easy cross referencing of code items within the documentation.
An application was required to scan C++ code and extract its significant code items and the comments associated with them. It had to convert this information into HTML source code which could then be viewed using standard Web browser software. The application should also create hypertext links between code items appearing in each file to produce a sophisticated cross referencing mechanism.
The principal code items to be documented in object-oriented software systems such as CABLE are the C++ classes. An HTML page has to be produced for each class, setting out its features in a clear, concise and consistent manner. As well as a description of the class, details of its interface and descriptions of its methods need to be given. Where references are made to other classes, structs or enumerated types there should be hypertext links to descriptions of these items.
The application should be designed to work with the GRACE C++ Coding Standard (GRACE/STA.6). The most relevant aspects of this standard are that a description of a class appears immediately before that class in the header file (.h) and that a description of each method in a class appears immediately before the implementation of that method in the body (.cc) file.
Due to the fact that a large quantity of code has already been written and requires documenting, the application should not require the coder to write anything other than C++. Some investigation was made into embedding commands into comments to enable the application to carry out more complex tasks, but on the whole the application should work from pure C++ code.
There were three options:
Two commercial products were assessed by the CABLE team for this purpose:
SNiFF+, available from Power Software, is already used by the CABLE team as the software development environment under which the CABLE project is managed. SNiFF+ has a built-in documentation feature similar to the utility that is required, however, experiments with the SNiFF+ facilities showed them to be poorly implemented and prone to failure (in the opinion of the reviewer at the time of the review). Hopefully the new version will solve these problems.
George, available from K2 Software, is a well established commercial product used for generating Framemaker, and now HTML, documents from C and C++ programs. George is highly configurable and in theory could deal with almost any standards for source code layout. It suffers however from being:
The internet was used as a source of research material into the subject of converting C++ to HTML. Several applications of interest already exist in this area:
Other similar applications also exist see Language Filters.
The descriptions of each of the applications below are taken from the relevant web page describing the application.
The Cxx2html software creates HTML pages from C++ header file information. It uses information from both the class declaration and the comments to create an HTML page which describes the class. The information extracted from the class declaration is used to create a class summary with links to the member function documentation and to the documentation for the classes which are parameters to the member functions. These links are created automatically from the class declaration.
Cxx2html is written in Perl 5.0, and it is currently used to create the library reference manual for the AIPS++ project centred at the National Radio Astronomy Observatory (NRAO).
The Ctoohtml software provides a C/C++ to HTML filter that came out of several desires/needs:
The Cocoon software filters C++ include files to produce a net of web pages that document the libraries, classes, and global functions and types that are found in them.
Cocoon relies on a small set of simple formatting conventions in the header files. Use of these conventions does not interfere with most formatting preferences, and does not obfuscate the code.
The obvious alternative to using an existing application is to develop a new one to meet our exact needs. This was the option that was finally chosen, for the following reasons.
The adoption of the GRACE coding standards for C++ mean that, in CABLE and other GRACE source code, method descriptions generally appear in the implementation files for each class. The conversion application must therefore access both the header file and the implementation file for each class. The Cxx2html and Cocoon applications only deal with header files, as do many of the other available applications. Ctoohtml was ruled out as this application merely `HTMLizes' C++ code, it does not extract the comments to turn them into documentation. Other applications that were available either:
Since the effort to create a utility in an interpreted scripting language was not considered to be too great, we chose to develop CGull from scratch.
Like most of the existing C/C++ to HTML converter utilities that are available on the Web, CGull is implemented in Perl 5.
The CGull application depends on an ability to parse the C++ code files passed to it. Perl is a language built around pattern matching and regular expressions and as such has a wide number of facilities for handling parsing. Although Perl can be quite a messy language, the introduction of object oriented features with Perl 5 allows well structured and designed code to be written easily.
Since Perl is an interpreted language, a copy of Perl is required in order to run CGull on you computer system. The latest version of Perl is available from the Perl Home Page.
A user guide has been prepared for new users of CGull. This guide has details on how to install CGull and prepare it for execution; how and where to run CGull; how to view the HTML produced by CGull and how to comment C++ code to get the most out of CGull.
Full class documentation for Cable, produced by CGull directly from the source code, is available on this server. See Cable documentation if you are a member of the GRACE Consortium. Sample CGull output is available for non-GRACE users which can be compared to the original C++ header and implementation source files.
For commercial or technical queries about CGull please contact:
[file:///protected/general/Footer.html]