Re: LuaDoc

[Matthew Frazier <leafstormrush@...>]

On 03/28/2011 09:13 PM, Alexander Gladysh wrote:
> I keep stumbling upon or hearing about a plethora of hacks that people
> do to reuse LuaDoc for their code. (I, myself, never tried to use it
> actually — being scared off by all these hacks.)
>
> So, I have a question: why hack around and why not to fix the tool (or
> write a new one for that matter)?

Not sure, really. Here are a few issues I have with Luadoc:

- The lack of ability to properly describe things like tables and 
classes. It's all just modules.
- The fact that while in theory it supports any kind of output, it 
pretty much requires you to use HTML to mark up your descriptions. Being 
able to write docs in Markdown would be better.
- Its reliance on API documentation rather than narrative documentation. 
This makes it hard to explain complex topics.

One thing I thought of was writing a Lua domain for Sphinx [1] with an 
autodoc extension. Unfortunately, while Sphinx is an amazing tool, its 
internals are very scary. Plus it's written in Python, which would 
probably drive people away on principle.

At any rate, a new, more flexible tool would definitely be welcome.

[1] http://sphinx.pocoo.org/
--
Regards, Matthew Frazier