lua-users home
lua-l archive

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


Hi all,

This is the 1.2 release of LDoc[1], which is a (mostly) LuaDoc
compatible documentation tool for Lua and Lua C extension code.  If
your existing LuaDoc-style documentation comments do not work in LDoc,
then it's a bug (unless you had to do a hack to get LuaDoc to listen
to you)

LDoc tries to infer more from code, and generally requires less
typing. Instead of

    @class module
    @name frodo

you may simply say

    @module frodo

since 'classes' act like tags.

There are extended tags like @tparam and @treturn

--- foo de doo.
-- @tparam s string
-- @treturn number

and you can define your own aliases for common tag combinations like
'tparam string' etc.  Such type information can be easily extracted
from the raw table output of LDoc.

It is possible to customize the output: - a nice example of custom
ldoc styling by Nils Nordman

http://nilnor.github.com/textui/docs/

It is also designed to work with Markdown (markdown.lua or
lua-discount) and aims to integrate any 'narrative documentation' and
examples with source-generated documentation. The big new feature of
this release is that it can handle multiple such documents, as can be
seen with the Penlight documentation.  It now explicitly keeps lists
of sections, so one can make references to subsections of a document.

As an experiment, any symbol in backticks like `select` will be
expanded like @{select} - but you can switch this off if it becomes
irritating.

Now works fine with Lua 5.2, and ... in formal arguments matches
anything; thanks for Dirk nagging me on this.

Documentation is at [2]; this version is available through LuaRocks as
'ldoc', and there is a zip here [3]; depends on Penlight (but it does
not have to be the very freshest)

Any feedback, complaints and style advice much appreciated.

steve d.

[1] https://github.com/stevedonovan/LDoc
[2] http://stevedonovan.github.com/ldoc/
[3] http://stevedonovan.github.com/files/ldoc-1.2.0.zip