RE: improving the Lua manual?

["John Hind" <john.hind@...>]

I agree that the return parameters ought to be shown, but I think the rest
of the conventions used in the manual are good, i.e. optional calling
parameters in square brackets and type information in the text. These
conventions can easily get overly formalistic and intimidating for new
users. Remember that calling parameters are often polymorphic so formally
documenting the types can get very complex.

For example, rather than:

io.open(filename [, mode])

I would write:

handle = io.open(filename [, mode])

Of course the return is also strictly optional, but that is always the case
so it does not need to be stated. Also the returns may be contingent - in
this case there is also a possible alternate:

nil, error = io.open(filename [, mode])

But this is a conventional error return so I'd mention it in the text only.
If there are two or more possible non-conventional returns, I'd show each on
its own line in the header. The advantage of the 'placeholder' variable
names is that it makes it natural and easy to refer to them unambiguously in
the description.

-----Original Message-----
From: lua-bounces@bazar2.conectiva.com.br
[mailto:lua-bounces@bazar2.conectiva.com.br] On Behalf Of steve donovan
Sent: 19 May 2009 08:35
To: Lua list
Subject: Re: improving the Lua manual?

On Tue, May 19, 2009 at 8:55 AM, Eike Decker <zet23t@googlemail.com> wrote:
> [2]: http://luxinia.de/doc/frames/actornode.html#pos
>

That's a nice notation, is [float x,y,z] meaning 'array of' or
'optional', or what?

A good point, we do need _some_ standard for specifying return values,
altho I'm happy with the LuaDoc convention. Your notation looks easy
to machine parse.

A sufficiently determined script could scrape the manual and generate
pseudo-Lua for LuaDoc.  I've often wanted to reference the Lua API
from my LuaDocs.

The manual is presumably generated from some source (HTML being so
shitty for writing); would it be possible to get that original source,
in whatever format?

steve d.

Attachment: smime.p7s
Description: S/MIME cryptographic signature