Configuring Doxygen for DoxyFilt

Doxygen provides a mechanism for filtering source code in order to make it more palatable to the Doxygen parser.

In the Doxygen configuration file, named Doxyfile by default, set the following:

INPUT_FILTER = DoxyFilt

Now, whenever Doxygen examines a source file, it will call DoxyFilt with the pathname of the source file and capture the standard output stream from the process. DoxyFilt will read the file specified and print out simplistic C++ code and/or Doxygen-enabled comments based on the contents of the file.

For example:

=item   C<parse($self [ , $path ])>

Parse the specified source file.

Applies all appropriate parsers the the source file.
Each parser is able to store information on itself
or this C<Doxygen::Source> object.

=cut

sub parse
{

generates documentation for Doxygen::Source::parse().

DoxyFilt.pl via batch/shell file/scripts

What Doxygen can't do is pass arguments or flags to the input filter. This is the primary reason why I use a batch file (on Windows) or shell script (on *NIX) to actually launch DoxyFilt.pl. I can reference the script from Doxyfilt and hide flags in the script.

Note:

I believe that originally (in my first attempt at this script) I did it this way because for some reason or other I couldn't invoke Perl scripts directly. In searching for references to Perl-to-doxygen processing scripts I found intimations of some problems with Perl on Windows NT/2000. Perhaps I too ran afoul of these and had to work-around with a .bat file.

For Windows the INPUT_FILTER setting executes the DoxyFilt.bat batch file. For *NIX it invokes the DoxyFilt shell script. Examples of these scripts are provided. The examples are the actual scripts used to generate the documentation you are even now reading (ta-daa!).

It is probably a good idea to generate a new set for each project, so that flag settings can be project-specific, but I have worked hard to have DoxyFilt.pl and the scripts provided do the most natural things I could think of.

DoxyFilt.pl Itself

The actual DoxyFilt.pl script has the following usage:

usage:  $0 <flag>* [ <path> ]
        Process file specified by <path> (or via --path flag),
        generating faux C++ and Doxygen comments to standard output
    --alias     <docType>=<filter>
                    set an alias for a document type, so that
                    <docType> is handled by the <filter> filter
    --check     <docType>=<pattern>
                    set the file recognition pattern for
                    a document type
    --comment   <docType>=<pattern>
                    set the comment recognition pattern for
                    a document type
    --docs      <docType>=<suffix>
                    set the suffix pattern for a document type
    --flag      <[docType::]flag>=<value>
    --help          show this usage description
    --noinfo        deactivate informational logging ([I])
    --pass=<suffix> suffix to be passed through unchanged
    --path=<path>   specify file path (or use positional argument)
    --spawn     <docType>=<command>
                    set command to be spawned via system()
    --trace         activate trace logging ([T] and [H])
USAGE