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