Re: LuaDoc

[Brian Maher <brian@...>]

Pretty much, I agree with what Sam says.

On Mon, Mar 28, 2011 at 8:10 PM, Sam Roberts <vieuxtech@gmail.com> wrote:
> On Mon, Mar 28, 2011 at 6:35 PM, joshua simmons <simmons.44@gmail.com> wrote:
>> Jakob and myself have been toying with this idea for quite a while now.
>> https://github.com/JakobOvrum/Loco Not super useful yet but we've just been
>> throwing around ideas really.
>> If people could define what they need from a documentation system that'd
>> probably be good.
>
> Should work for code both implemented in C, and in lua, and in a
> mixture of C and lua.

Writing docs in C code is super important to me.

> Should support lightweight markup, javadoc-style is OK, markdown with
> some extensions would be nice.

I agree that markup support would be great.

> Should be able to figure out function/method name and parameter names
> from the definition.

...to a certain point.  For C code there is no obvious way to
determine any of this information.

> Should be able to be told whether functions are intended to be called
> as methods (: with implicit self).

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.  Note that for the fields of an object, there may not be
any associated function.  Also, it would be nice to declare what the
expected metatable of an object is so you can find out what fields
would be "inherited" and what operators are overloaded.  Also, if any
"type" is a function it would be nice if I can recursively document
the inputs and outputs of that function.

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

> Would be really nice to have an abstract output (lua tables...?), with
> a concrete generator for HTML, but  the possibility for man pages,
> text, xml, etc.

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

> Thats my with list. I've a cheesy utility that I use because its
> simple, gives text output, and hides the difference between C and lua
> (and doesn't do much else).
>
> And personally, I don't care what language its written in, as long as
> the language has built-in regular expressions. ;-P
>
> Cheers,
> Sam
>



-- 
Brian Maher >> Glory to God <<