[Date Prev][Date Next][Thread Prev][Thread Next]
- Subject: Re: LuaDoc
- From: Matthew Frazier <leafstormrush@...>
- Date: Mon, 28 Mar 2011 21:44:16 -0400
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  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.
Regards, Matthew Frazier