Re: Doxygen for Lua

[Tim Mensch <tim-lua-l@...>]

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:

http://www.lulu.com/content/paperback-book/navigating-the-playground-sdk%E2%84%A2/697902

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

You can also download a PDF from http://developer.playfirst.com, 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...

Tim