lua-users home
lua-l archive

[Date Prev][Date Next][Thread Prev][Thread Next] [Date Index] [Thread Index]

dcharno wrote:
Anyone using Doxygen to document their Lua code? A search on this topic turned up nothing. I know there is Luadoc, but my C application is already documented with Doxygen and it would be nice to have the Lua extensions documented similarly.
Oddly enough...yes. There are Lua docs generated as part of my book:

Took advantage of the Doxygen LaTeX output, and poof, a book. Does LuaDoc do that too? :)

You can also download a PDF from, if you're curious.

In any event, what I wrote (in Lua, no less, though wrapped in an EXE to allow Doxygen to call more easily) was a quick preprocessor that makes Lua code look like C++ code. Really it's a pretty simple hack: I only look for (and document) functions and global constants. When the preprocessor finds a "---" comment section, it removes the "---" and wraps it in C-style Doxygen comments, and then after the comment leaves just a function header, like so:

 My docs.
function MyFunction( foo );

Doxygen then deals with this more-or-less correctly. Of course it thinks it's a function returning type "function," taking a parameter type "foo", but it produces the right output, so that's fine by me. :) For parameters, I added a couple of Doxygen aliases; you might be able to get away with @param, but Doxygen spits out warnings (parameter not found!), and I wanted to be able to label the type of parameter expected:

--- Pause for some amount of time.
--- \luaparams
--- \luaparam{time,number} The number of milliseconds to pause. \endluaparam
--- \endluaparams
function Pause( time );

Again, it took a more complex syntax because of how the LaTeX output worked. I could have probably hacked Doxygen directly to make it easier, but it's better to use the stock Doxygen when you can, and I'm not up to writing a full Doxygen input filter to contribute to that project at the moment.

\return works correctly in LaTeX, or at least correctly enough, so I didn't need to jump through any hoops there.

Unfortunately I can't just upload the code that does all this without seeking permission from my company, which gets complicated...but seriously, it's not hard to write a quick preprocessor as I just described, and it gets you basic documentation ability from within Doxygen. Once you have a preprocessor, Doxygen can use it directly--from my Doxyfile:

FILTER_PATTERNS        = *.lua=c:/depot/tools/luatodoxygen/luaToDoxygen.exe

If you have any more Doxygen-specific questions, feel free to contact me off-list. I feel like I've already drifted perilously close to completely off-topic, even though I am talking about how to use Doxygen to parse Lua docs...