Return to Europa
The goal of this project is to develop a cross-linked documentation browser for RESOLVE/C++ projects. RESOLVE files and comments follow a strict convention as to their format. Information contained in these formats can be parsed by a program to generate cross-linked documentation. The documentation system will eventually support online documentation browsing, syntax-highlighting and cross-linking of source code, and generation of printable documentation.
Many past Europa projects have attempted to parse RESOLVE to acheive some ends. This is a very ambitious goal which was not attempted. The source code is being preprocessed into 'C++ with less macros' + 'comments'. The RESOLVE macros and comments are being combined and translated to form Doxygen-formatted comments. The preprocessor is being implemented as a three-state parser: pure code, string literals, and comments. Regular expressions are applied on the source code for processing. Very basic state information is being kept such as which class is being processed currently and which method comments refer to. C++ -isms in Doxygen are being removed by the means of translation of the program into a new language other than English: 'RESOLVE-speak'.
The generated BugsWorld Catalogue documentation (as generated by Doxygen 1.3.5-cvs) can be viewed at
www.cis.ohio-state.edu/europa/projects/0062/bugsworld/.
The generated RESOLVE Catalogue documentation (as generated by Doxygen 1.3-rc3) can be viewed at
www.cis.ohio-state.edu/europa/projects/0062/resolve/.
The tools used to generate these files can be downloaded here: resolve2dox.tar.gz.
These include most notably the resolve2dox.pl source code filter, a modified version of Dr. Bucci's rcpp2html, and a preconfigured Doxyfile.
Doxygen and AT&T's Graphviz are needed for operation.
A basic preprocessor for RESOLVE/C++ has been developped and was used to generate documentation. However, several difficulties were encountered during this project. A bug in the underlying third-party tools prevents the full RESOLVE catalogue from being properly parsed. Some reasons for this include improper matchings of templated method declarations and implementations. Another factor is that small variations in the current RESOLVE/C++ component catalogue make machine processing difficult. The most limiting factor for this project, however, is that Doxygen cannot handle prototypes (inserted into the documentation) in RESOLVE-format. This means that even when writing a translation of Doxygen into 'RESOLVE-speak', the resulting documentation will be too C++ -oriented for production use. Future work could include writing an input processor for Synopsis (see Links and References) to handle RESOLVE. Synopsis has true support for pluggable input languages.