DoxyFilt: DoxyFilt.pl File Reference

Script for preparing non-C/C++ input documents for Doxygen. More...

Detailed Description

Script for preparing non-C/C++ input documents for Doxygen.

SYNOPSIS

In Doxygen configuration file:

  INPUT_FILTER = DoxyFilt

The DoxyFilt entry will be a batch file or shell script that in turn invokes DoxyFilt.pl. For example (DOS/Windows batch file):

  set doxpath=%~p0
  perl %doxpath%DoxyFilt.pl %1

or (Linux shell script):

  #!/bin/sh
  perl DoxyFilt.pl $1

Any command line parameters necessary to DoxyFilt.pl will be invoked in the batch file.

Note that in more complex situations, where a number of languages are used, the batch file or shell script will need to choose the appropriate filter (DoxyFilt.pl or another program) and invoke it.

ABSTRACT

Provides an input filter for the Doxygen documentation generation tool to convert Perl/POD (and/or other source formats) into C/C++ with Doxygen-enabled comments.

DESCRIPTION

The Doxygen documentation processor collects information from source code files in C and C++ and generates nicely formatted source code documentation. This can be an important component of any fully documented software project.

Unfortunately, Doxygen doesn't know anything about any other languages. It does, however, have an input filter setting that allows source files in other languages to be converted to something that Doxygen can recognize. This means parsing the source files and converting them into a combination of C/C++ and Doxygen-enabled comments.

Command-Line Arguments

The following flags can be specified to affect the operation of DoxyFilt.pl:

--alias I<filter=existing>: Specific a filter that will be handled by an existing filter. Use this when it is necessary to specify multiple filters that use the same filter module but have different characteristics. For example, Batch and Shell both link to the Script filter by default, but use different comment patterns.
--comment I<filter=comment>: Specify a comment pattern for a given filter. Only one comment pattern may be defined for a given filter, new ones with old filter names replace the old patterns.
--check I<filter=recognition>: Specify a recognition pattern for a given filter. This is used for files without suffixes. Any such file is tested with all registered patterns of this type and the specified filter(s) are applied.
--docs I<filter=suffix>: Specify a suffix to be handled by a specific filter. Filters may be added by the user and specified in this manner. The default filters include Perl, POD, Batch, and Shell. More than one filter may be applied to the same file. Only one suffix pattern may be defined for a given filter, new ones with old filter names replace the old patterns.
--flag I<[docType::]name=value>: Specify a named flag. Flags can be specified as global or per document type. More specific flags (per document type) override global flags for the specified document type and are invisible to other document types.
--noinfo: Deactivates informational messages such as those that specify what file is being processed. These are the [I] messages.
--pass=I<suffix>: Specify a suffix to be passed through unchanged. This flag may be used multiple times. Defaults to dox or doxy (Doxygen source files). Flags are cumulative, and can't be removed, but may be overridden by --docs.
--path=I<pathname>: Alternative way to specify pathname of file to be processed. Normally it is specified by the positional argument, but it can be set this way instead. This flag takes priority over the positional argument.
--spawn I<filter=command>: Specify a command to be executed as a subprocess to implement a given filter. In this case there will be no matching Doxygen::Filter subclass, just specify a --docs setting to 'declare' the filter name and its suffix and then use the --spawn parameter to set the command to be executed. The pathname to be processed is appended after a space to the end of the command line, or it will replace the string '{}' if these are present in the command.
--trace: Activates tracing and 'hacking' messages. The former are lower-level debugging messages. The latter are specific conditions that have been bypassed in possibly strange ways (if any). These are the [T] and [H] messages, respectively.

Where the above flags specify suffix the argument will be converted into a pattern. If a simple string or pattern fragment it will be embedded in the pattern qr(\.$string)i. If it matches /^qr$(.*)$$/ it will be converted via qr($1).

Arbitrarily complex patterns should be possible when appropriately quoted to get past the operating system's command line interpreter. The following appears to work on Linux:

  perl DoxyFilt.pl '--pass=qr(\.doxy?)i' --docs 'Batch=qr(\.bat)i' ...

In a similar fashion, where flags specify suffix the argument will be converted into a pattern. In this case, if it is a simple string it is embedded in the pattern qr(^\\s*$string(.*)$)m. If the string matches the qr() format it will be converted directly as with suffix patterns.

COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

Version:: '0.75'

Author:: Marc M. Adkins mailto:Perl@Doorways.org

Definition in file DoxyFilt.pl.