lua-users home
lua-l archive

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


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