Re: [Doxygen-develop] Custom commands with arguments?

[Iain B. <ia...@pc...>]

Hi,

On Tue, 2006-09-26 at 22:43 -0500, Dirk Reiners wrote:
> 	Hi everybody,
> 
> we've been thinking about integrating doxygen better with Trac, and one 
> solution would require custom commands with arguments. This is listed as 
> #28 on http://www.stack.nl/~dimitri/doxygen/todo.html, so apparently 
> somebody else would like it, too.
> 
> Is anybody working on that, and if not, can anybody give me a hint on 
> where to start and how to get it done?

I don't know how well it will fit your outcome, but I made a perl script
that you use as a pre-filter to the source code.  It looks for custom
commands that you put in a command file, and replaces the
doxygen-looking alias with what you specify from the file.

It sounds the same as the way doxygen does it except that you can put
latex or html before _and_after_ the doxygen tag.  eg:

=== doxygen way: ===

source file:
/**
 * @cmd world
 **/

doxygen.cfg:
ALIAS="cmd=<b>hello</b>"

output
<b>hello</b> world

=== my way: ===

source file:
/**
 * @cmd hello world
 **/

filter.txt:
'cmd', '<b>', '</b>'

output:
<b>hello world</b>

You can see the subtle difference - effectively "hello world" is an
argument to the command "cmd".

In reality, this is _very_ powerful.  I've created some very nice
looking pdf's using this filter, however it may not work so well for
you, because I customised it just how I wanted it, without thought for
other uses.  I've attached it anyway.  YMMV!

You use it like this:
doxygen.cfg:
INPUT_FILTER = "perl -w filter.pl filter.txt"

filter.txt:
'tag', 'html open', 'html close', 'latex open', 'latex close'

an argument is ended by either the start of a new alias (ie. '@') or the
end of the comment block (**/) you may want to change that to */

ie:

/**
 * @cmd1 argument to command 1
 * @cmd2 argument to command 2.  This
 * one wraps around.
 * @cmd3 arguement to command 3.
 **/
<c++ item to be documented>

The filter also keeps line numbering the same, so that you can still use
doxygen line references.

HTH!

-- 
Iain Buchanan <iain at pcorp dot com dot au>

Cats, no less liquid than their shadows, offer no angles to the wind.