lua-users home
lua-l archive

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


Naturaldocs lookd insteresting. Do you have an example of code and documentation ? From a wiki page [1], it seems that we need to add a lot of redundant stuff in the docs.

Another interesting route to explore is to use Lua's first comment block on each page --> markdown (simple parser) and then use pandoc (this is what allegro.cc is doing).

Gaspard


[1] http://wiki.garrysmod.com/?title=Documenting_Lua

On Tue, Mar 29, 2011 at 11:29 AM, Michal Kolodziejczyk <miko@wp.pl> wrote:
On 29.03.2011 03:44, Matthew Frazier wrote:
> 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.

I use NaturalDocs: http://www.naturaldocs.org/
It is not ideal, but:
- can document many source languages at the same time (C/Lua/PHP/...)
- easily supports narrative docs
- output looks nice
- uses searching (using _javascript_ only)

So it gets the job done for me.

Regards,
       miko