[ANN] LDoc 1.0 A Lua Documentation Tool

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

Hi all,

This a beta release of the new ldoc [1]  which is a new and
(hopefully) improved version of LuaDoc.  Existing doc comments in the
LuaDoc style are understood, but there are several extensions that can
make life easier.  Idoc can be also used with C/C++ extensions, and
markdown can be used to process comments (tested with both
markdown.lua and lua-discount)

The major new features are support for examples and a extra
documentation file in Markdown format; the most elaborate example
currently is Winapi [2]  Code samples and code blocks in the
documentation are pretty-printed (although there is a @plain directive
to switch this off)

As a bonus, you can use ldoc as a quick-and-dirty console help
utility. If you have installed modules which have LuaDoc comments,
then ldoc -m will give a summary of the contents:

ldoc -m luarocks.search
ldoc -m table.sort

Also works for built-in Lua functions and tables, plus LPeg and
LuaFilesystem due to the excellent luadoc files provided by mitchell's
Textadept project.

[3] is an example of 'no nonsense' documentation style using that
project's .luadocs for the Lua libraries; ldoc allows you to write
tag-less documentation by suppressing the usual 'Parameters' and
'Returns' sections in the output.

Thanks to Norman Clarke for initial discussions and Lorenzo Donati for
brainstorming and painstaking testing!

These are the areas that need most improvement:
- LDoc uses a lexical scanner to analyze Lua code; it may not always
get it right - Lua is a very flexible language. You should be always
able to override any miss-guesses with explicit tags.
- The template and style sheets have been modified from the original
LuaDoc files and the result is not as attractive as it could be. (This
is not my strong point, so any suggestions are welcome)

steve d,

[1] http://github.com/stevedonovan/LDoc
zipball here: http://stevedonovan.github.com/files/ldoc-1.0.zip
online docs here: http://stevedonovan.github.com/ldoc/

[2] http://stevedonovan.github.com/winapi/api.html
[3] http://stevedonovan.github.com/lua-stdlibs/