Re: [ANN] LDoc 1.0 A Lua Documentation Tool

[Hisham <hisham.hm@...>]

On Mon, Sep 26, 2011 at 8:13 AM, steve donovan
<steve.j.donovan@gmail.com> wrote:
> 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)

Kudos for the tool! I will certainly give it a spin. Some feedback
from skimming through the generated docs:

* In [1], the title "winapi" seems misaligned from the rest (on
Firefox 6 at least). It's touching the upper margin of the document
and it also has less left-padding then the other elements of the
sidebar. There are a few other spacing details bugging me here and
there, I'll try to take a closer look at the CSS file later.

[1] http://stevedonovan.github.com/winapi/api.html

* When I clicked on the sections of the "Contents" list in the
sidebar, it took me directly to the functions; I expected it to take
me to the relevant section in the TOC at the top, so I could click on
"Class Regkey" and then get a overview of what are its functions.

* Sections are hard to catch visually when scrolling through the file.
I suggest colored backgrounds like you see in x and x.y sections of
the Lua manual [2]

[2] http://www.lua.org/manual/5.1/manual.html

Any particular challenges in getting a rock done for LDoc? I had to
jump some hoops to get LuaDoc running with LuaRocks, so I suspect
there may be some similar issues (locating template files?). We can
discuss this further in the LuaRocks mailing list.

-- 
-- Hisham
http://hisham.hm/ - http://colorbleed.com.br/