|
|
|
|
|
The find_extract.pl perl program is a handy tool for API applications that would tend to contain too much noise. It generates a temporary file from many source code files. The temporary file contains only those code items of interest.
In more general terms, the problem was that the engineers working directories often contained more code files and code in general than what was required by down-stream API users. When I ran Doxygen on these files and directories, it would pick up many more code items than were useful and significantly added noise to the output.
For one API project, I had C++ classes which implemented functions to an internal Pascal-like programming language.
For another project, all sub-projects created and exposed to all users a small set of functions. These functions were distributed throughout the code and were surrounded by the C++ code that made them possible. (These were called xhelp functions, which is why the x creeps through in implementation and descriptions.)
From the onset, this tool needed to support different requirements in terms of what was passed through to the temporary file.
Hence, each project can define its own xscope, which is a perl module that limits it definitions to the contents of several data types that are used later.
input_scope A file path and name to a perl package that has the to-be-included and to-be-excluded code items commands.
root_path_to_files must be terminated with a forward (\/) slash. If output file does not have a forward slash (\/) -- an indication of a path --, then the <root path to files> is assumed.
output_file the name of an another file. This file, plus one similarly named with a leading underscore are generated. The file without the underscore is intended as the input to Doxygen.
The input_scope file is the key to the successful operation. It is required to have:
The xscope perl package definition.
Routines
» declare_variable.
» memory_clean_up.
Arrays:
» x_names, which contains all prefixes that could be of interest.
» needed_in, which contains a list of xhelp commands that are absolutely needed-to-be-in.
» needed_out, which contains a list of commands that we don't want to expose at all if they happen to come through.
» include_f_type, which are file types that should be viewed.
In short, the find_extract.pl perl outputs these files:
<output_file>.gen which has part of its name specified as an input parameter. It contains the located code item and all associated doxygen comments. This has only a prototype definition; the actual code body for the code item is empty.
Example: When global (xhelp) functions were dispersed around the code pool, this file would put the function prototype and its associated comments in this file.
<output_file>_class.gen which has part of its name specified as an input parameter. It contains the definitions of any classes, their member functions of interest, and their associated comments. This has only a prototype definition; the actual code body for the code item is empty.
Example: Sometimes developers have classes with many member functions, but only several of which that they want to expose in the documentation. This file would contain only those classes and member functions deemed worthy of exposing. It saves the developer from having to play tricks with private and public declarations. Moreover, in my case, the exact member function name was not actually exposed, but something similar.
<output_file>_dox_template.gen which has part of its name specified as an input parameter. It contains just the associated doxygen comments.
Example: For one project, developers implemented a Pascal-like language using C++ classes. The Pascal code that was exposed to users was generated. The appropriate place for the documentation of the end-user functions was on a class member function definition. These comments needed to be found and extracted. I used the same code generation tools as the developers to generate a different temporary file with the function definitions that matched what came out of the extracted doxygen comments. Both files were then used as input into doxygen.
<output_file>_list.gen which has part of its name specified as an input parameter. It contains a list of located code items and a checklist whether or not they had doxygen comments.
Example: This file was used mostly as communication between Technical Publications and Engineering. It showed which code items I found and whether or not they were commented as expected. Engineering was expected to review the list, remove code items that werent supposed to be picked up, add code items that were, and comment those items that were flagged as not having templates.
Depending upon the application, any of the files except the <output_file>_list.gen file could be used as subsequent input into doxygen.
Note: The output files used as input to Doxygen have only prototype definition; the actual code body for the code item is empty. Doxygen doesnt care about the implementation details below the definition of the code item, and neither does the API reference documentation.
The find_extract.pl perl program does divide and conquer.
1 The find_extract.pl perl program greps the code
Using the prefix list and looking at the file types of interest.
Using the command list and looking at the file types of interest.
This information is placed into a very temporary file.
2 The temporary file with grep results is stripped of non-interesting entries.
3 A file hash is created that is a hash of hashes.
$file_hash {$src_file} {$code_item} {r} {$return_type} = unimportant number $file_hash {$src_file} {$code_item} {p} {$prototype} = doxygen
It contains:
{$src_file} the source code files where items of interest were found.
{$code_item} code items of interest, each associated with a source file.
{r} {$return_type} a hash of return types for each code item; supports overloading.
{p} {$prototype} a hash of code definitions for each code item; supports overloading. It contains to the doxygen comment block.
4 The source files from the hash are
opened and searched for their respective code item definitions.
are searched for comment blocks associated with the code item definitions.
5 The file hash is
fleshed out for the prototype definitions and their respective comment blocks.
is stepped through and output to generated files. The generated files are intended for input to doxygen.
The final step is the temporary output files are generated easily based on the information in the hash tables. The output files have only prototype definition; the actual code body for the code item is empty. These files are used as input to Doxygen. Doxygen doesnt care about the implementation details below the definition of the code item, and neither does the API reference documentation.
|
|
|
Open-Source tools compliments of Voyant Technologies, Inc. and Glenn C. Maxey.
01/13/2003
TP Tools v2-00-0a
# tpt-hug-02