Re: LuaDoc

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

On Wed, Mar 30, 2011 at 3:52 PM, Brian Maher <brian@brimworks.com> wrote:
> I *really* also want support for "types" of inputs and outputs.  In
> particular, if I have a function that returns an "io" object, then it
> would be nice to be able to declare what methods/fields exist on an
> "io" object.

Actually, LuaDoc can do this for you, since tables may be documented,
and there can be a @see reference to them in the function docs.

In the Lua world we have a bad habit of using anonymous data structures ;)

> Also, don't forget that functions may have multiple outputs.

There may be multiple @return annotations for a function in LuaDoc.

> Lua table output seems the most logical "native" output.  It would
> then be trivial to convert lua tables into other formats.

Well, not quite trivial ;) I think a lot of the push back about LuaDoc
is that people don't like the default templates - but they are
templates and can be customized.

(And that output format needs to be pretty well documented!)

LuaDoc was designed to be very general, but never achieved any benefit
from this.  It just made modifying it a royal pain (just a personal
experience here)

What Norman Clarke and I have been discussing is something that
initially does LuaDoc-style annotations, but allows for pluggable
markup (most likely Markdown) and is more robust and friendly-error
generating.[1]

And, ideally, a means of customizing the parser, so that you can teach
it _your_ style of class declarations (as Mr Pasternak has done with
his Lua->C++->Doxygen converter) and ship that customization module
with your project.

Arguably, this is another wheel-reinventing exercise, but the
prototype is already doing my Penlight documentation, and was worth it
just for that; the question is how far to push the project.

steve d.

[1] like actually giving a file:lineno when issuing an error/warning.
These things matter ;)