[ANN] LDoc - A documentation tool for Lua

[steve donovan <steve.j.donovan@...>]

Hi all,

LDoc [1] can be seen as another implementation of LuaDoc, and aims to
be compatible. Since the templates and stylesheets have been
shamelessly copied from LuaDoc, the result even looks the same.  It
came out of the documentation needs of Penlight and some discussions
with Norman Clarke where we agreed that there was room for a new kid
on the documentation block.

It aims to provide better feedback (e.g. giving file:line references
when a @see reference can't be found), works with C/C++, and can
optionally use Markdown in comments.

You can ship your own stylesheet (and even template) as in this really
minimal Markdown-driven style [4]

The winapi docs [5] gives an example of how features like @section
tags and @type tags can be used to document over-long modules ;)

As a bonus, it can be used as a handy desktop reference:

  $> ldoc -m assert

    function        assert(v, message)
    Issues an error when the value of its argument `v` is false (i.e.,
     nil or false); otherwise, returns all its arguments.
    `message` is an error
     message; when absent, it defaults to "assertion failed!"

Thanks to mitchell's TextAdept [6] project, ldoc has .luadoc files for
the standard Lua libraries, plus LPeg and LuaFileSystem.

'ldoc -m' looks on the module path, so any available module with
LuaDoc-style comments can provide online help:

 $>  ldoc -m pl.pretty.write

    function        write(tbl, space, not_clever)
    create a string representation of a Lua table.
    tbl      {table} Table to serialize to a string.
    space    {string} (optional) The indent to use.
                   Defaults to two spaces.
    not_clever       {bool} (optional) Use for plain output, e.g {['key']=1}.
                   Defaults to false.

A zipball is available directly from [2] and the docs have been
rendered at [3].  Depends on Penlight [7]


steve d.


[1] https://github.com/stevedonovan/LDoc
[2] http://stevedonovan.github.com/files/ldoc-0.4.zip
[3] http://stevedonovan.github.com/ldoc/
[4] http://stevedonovan.github.com/ldoc/custom/
[5] http://stevedonovan.github.com/winapi/api.html
[6] http://code.google.com/p/textadept/
[7] https://github.com/stevedonovan/Penlight  (luarocks install penlight)