[ANN] LDoc 1.3

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

Hi all,

Thought that I could at least get a new LDoc release out by Russian Christmas ;)

LDoc[1] is a next-generation Lua documentation tool which is intended
to make the task of documenting Lua and C Lua extensions as painless
as possible while staying largely compatible with LuaDoc. You can
browse the docs here [2], pick up the zip at [3] or directly use the
rockspec at [4]

This is the first release candidate for 1.3, which has some new
features (translation: new bugs?). Thanks very much to Geoff Leyland
as chief collaborator.

The best way to introduce some of the new features is an example [5].
A big focus is making it easy to provide type information for
parameters and return values.

If @ signs irritate you intensely, you can use colons like so:

--- second useless function.
-- Note how these types are rendered!
-- string: name
-- int: age
-- ?person2: options
-- treturn: ?table|string
function two (name,age,options)
end

Thanks to Geoff for implementing the ?T1|T2 notation for the common
situation where the parameter may be of several types. ?T simply means
that this value is optional.

If this style floats your boat, then this could also be documented like so

--- second useless function.
-- Note how these types are rendered!
function two ( -- ?table|string:
    name, -- string:
    age,  -- int:
    options -- ?person2
)
....
end

(The output of LDoc does not just have to be HTML, since the inner
representation can be passed to a custom processor.)

Dealing with the multiplicity of styles seen in the wild has been a
particular challenge - the styles subdirectory of the tests attempts
to provide a catalogue of possibilities.

I should emphasize that you do not need to use the 'tag soup' xxxDoc
style at all. Have a look at [6] which shows the Lua 5.1 standard
libraries, from the luadoc files provided by mitchell's Textadept
project. These are included in the LDoc source, so that it's possible
to browse the Lua documentation (or any LDoc-enabled module on the
path) using this:

$ ldoc -m table

An entertaining challenge for 1.3 is upgrading the old templates and
stylesheets, which aren't much changed from LuaDoc and starting to
look a bit dated.  And (as a mobile developer connection said) the
output looks terrible on mobile. There is a 'one' flag for config.ld
that makes a single-column output, but clearly we need some CSS input
to make it beautiful on the tiny computers of the future.

steve d.

[1] https://github.com/stevedonovan/LDoc.git
[2] http://stevedonovan.github.com/ldoc/
[3] http://stevedonovan.github.com/files/ldoc-1.3.0.zip
[4] http://stevedonovan.github.com/files/ldoc-1.3.0-1.rockspec
(if you're using an older version of luarocks, the executable will be
available as 'ldoc.lua')
[5] http://stevedonovan.github.com/ldoc-example/
[6] http://stevedonovan.github.com/lua-stdlibs/