Search code examples
filterdoxygen

Doxygen filter format?

With my team we create software we need to document. I have found doxygen which seems a nice program to do this. Although our programming language is not supported (RAPID).

Yesterday I have asked a question about this. Albert was kind enough to provide a clue in the right direction. A filter should be the right way to go in stead of an preprocessor.

But I did not provide the syntax of the RAPID code which can be found here : http://futurecnc.code.arc.cmu.edu/wp/wp-content/uploads/2011/12/RAPID-Reference-Manual-Instructions.pdf

I found the help guide about creating filters from the doxygen website. Also i have found an example filter created by Bert Jordan for perl :
http://www.doxygen.nl/helpers.html

Some questions :

  1. Is a filter the right way to go, or is a preprocessor needed ?
  2. What is the filter exactly doing ?
  3. Doxygen has an lexical scanner, what kind of format must be used for the filter to convert the rapid code to a supported language?

I hope, I have given a clear description now :)

edit : I'm searching for information about how to create the actual filter. Does anybody know a good source for this ?

Solution

  • There are some examples on filters for other languages at the Doxygen site under the helpers section.

    I have used a Doxygen filter (which is not listed there) for Bash for one of my projects. The filter is pretty simple and might be a good example. This filter is available at Anvils GitHub.

    In essence, it is just a ~130 line sed script converting bash to quasi-C which Doxygen can parse. You could write your own sed script for RAPID.

    You should add it to your Doxyfile with:

    # Tell Doxygen to handle files with sh extension as C files
EXTENSION_MAPPING = sh=C

# Tell Doxygen to run sh files through the below sed script
FILTER_PATTERNS        = *.sh=MY_PATH/doxygen-bash.sed

    There is also a python example via the helpers page here.

    The main part to understand is that the filter can be anything you like to write. Python, sed, shell, etc. Doxygen just calls your filter, runs the code through it, and your filter should output a language Doxygen can parse.