[Doxygen-develop] New tags...

[John O. <jo...@ly...>]

I propose that three new tags are added

@run
@endrun
@filename

Why do I need these tags and what do they do?

The problem I'm trying to solve is that I want to add the ClearCase (our
version control system at work) version number for the documented files in
the generated documentation. And while doing this I thought that I could
solve a more general problem at the same time. :)

The @run and @endrun tags are a pair, much like the @link and @endlink
tags. The tags are used for calling a program and inserting everything
that the program sends to its stdout directly into the generated file.
Thus I could, for instance, write a simple script that extracted the
intersting information using the cleartool command and so on. :)

I have done a prototype implementation of this based on the iSystem()
function found in util.cpp, but since I'm not a Windows programmer I have
only done the Unix part of it...

The @filename tag simply inserts the full filename (path + filename) of
the current file in the generated documentation and in my current
prototype implementation it can only be used between the @run and @endrun
tags. It simplifies life if you do not need to hardcode this in the source
code...

So, if I tidied up my implementation, would this be something that you
think would be useful for others? If so, could someone help me with the
windows programming bit?


Perhaps I should give you an example? Here it is

/**
 * @file foo.c
 * ClearCase version: @run myScript @filename @endrun
 */

When the parser recognises the @run (and @filename) tag(s), the following
command is executed

myScript /vobs/myvob/foo.c

And the output from this script could look like this

/vobs/myvob/foo.c@@/main/mybranch/17

And finally this is inserted into the generated documentation, resulting
in this

ClearCase version: /vobs/myvob/foo.c@@/main/mybranch/17


/John