How to extend Doxygen to support Lua? Or: how to write Doxygen filters?

Question

I am working on a code base that is one half Lua and one half C++. We use Doxygen to document our C++ code.

Now, we want to use Doxygen for the Lua part, too. But Doxygen lacks support for Lua.

There is a project that kind of adds Lua support for Doxygen. It is written in Perl and I understand what it does. It implements a filter that converts a Lua source file into something that Doxygen can parse. However, Doxygen does not seem to recognize all the functions etc.

So my question really is: What is the format Doxygen expects from the filter?

Answer 1

The strict answer is that your filter should produce grammatically valid output in a language doxygen supports (you can use EXTENSION_MAPPING to map the file extension for your language to a supported language).

Since doxygen's parser is rather loose (it is a lexical scanner, not really a parser), it might work as well if you do not 100% follow the grammar rules of the language, but it will be a trail and error process to find out which deviations are allowed and might break if you upgrade to a future version of doxygen.