CodeEnforcer Configuration

As stated earlier, HadronZoo::CodeProc (or simply CodeProc), is a psudo compiler and document assembly program that examines a C++ code body, identifies key items of interest (e.g. classes and member functions), from which it compiles a technical manual suitable for online publication. The manual takes the form of a host page, with a navtree to the left and a viewing area to the right. Manual pages, of which there one per item of interest, are upon selection from the navtree, loaded by means of AJAX into the viewing area.

This is very similar to what Doxygen does, and Doxygen was considered for the role CodeProc plays in the HadronZoo code acceptance process. Although Doxygen is well established and arguably superior, it imposed a comment format that HadronZoo was reluctant to adopt on the grounds of poor code readability. More importantly, HadronZoo was keen to develop a code documentation tool in order to gain compiler writing experience.

The term 'item of interest' requires qualification. Each class, struct, or union, each function (member or non-member), and each enum, is a potential item of interest. However, not all these entities would warrant their own page. Functions can be grouped together because they are overloaded, similar or both, while those inlined in a class defininition, appear only in the page for the class. In addition to the item of interest arising from the above C++ entities, global variables are collected together as an item of interest, and further items of interest are inserted in response to comment blocks which begin with the 'Synopsis' keyword. single page.

The CodeProc XML config file defines for each project components (library or a program that may or may not depend on a library), a set of C++ header and source files. Then for each header and source file, CodeProc does much that a C++ compiler would do. It tokenizes the files, parses the tokens into statements, then builds an entity table from the statements. The entities are then grouped into items of interest.

The config for the HadronZoo library, would look something like this:-

<pre> <codeproc name="hzlib" hostpage="/hzManual" copyright="HadronZoo Project 1999-2024"> <website addr="http://www.hadronzoo.com"/> <htmldir path="/home/hadronzoo/websites/hadronzoo.com/www/HadronZoo"/> <library name="hzlib" title="HadronZoo C++ Class Library"> <desc>Library for development of standalone Internet applications and backend processing systems</desc> <hdrs dir="/home/hadronzoo/hzraw/code/hzlib.10.0/inc" files="*.h"/> <srcs dir="/home/hadronzoo/hzraw/code/hzlib.10.0/src" files="*.cpp"/> <docs dir="/home/hadronzoo/hzraw/code/hzlib.10.0/doc" files="*.txt"/> <view> <item_header name="Headers"/> <item_source name="Sources"/> <item_ctmpl name="Class Templates"/> <item_class name="Classes"/> <item_enums name="Enums"/> <item_funcs name="Global Functions"/> <item_notes name="Notes"/> </view> </library> </codeproc> </pre>

In the above, the root tag 'codeproc' names the project and sets the copyright notice. The website tag states the target website (optional), while the htmldir tag states the target directory of the output files (compulsory). There is no component tag as such, and components are defined as either a library or a program (with either a library or a program tag). The component subtags then define the set of header and source files and if present, a separate set of document files. The view tag states which groups of items of interest, will appear in the navtree and in what order. By default however, all the groups will appear and in the order shown.

In a CodeProc config for a program (assuming dependance on the HadronZoo library), the library tag comes first and is followed by a program tag. The program tag has the same set of legal subtags that the library tag has, except that the headers and source (and any document) files, will usually be in the same directory. If the intention is to onlt show program items in the navtree, the view tag in the library tag is omitted, otherwise the navtree will have a branch for the library and a branch for the program.