Re: improving the Lua manual?

[Eike Decker <zet23t@...>]

The notation in my sample is purely hand written as description for
the function (meh) - but I don't see another way for doing that
automatically. The notation in that case means
float x,y,z =means: x is of type float as well as y and z (until a
different type follows, i.e. "table tab")
and [float x,y,z] means that this is optional and might be left out.
In that specific example this means:

local x,y,z = node:pos() -- returns the x,y,z coordinates of that node
node:pos(x+5,y,z) -- sets x,y,z - no values are returned

Since the return values rely often on the input (i.e. returning
nothing or any other number of values) I don't see a specific
convention that applies to any case. Thus I would write for a function
that has a non-trivial return value

(...) nontrivialfunction (input a, input b, ...)

... and writing the rest in the function description. However, most
functions that I have used so far have pretty static return values,
for example the "loadfile" function that returns true on success
followed by either an error message or the compiled function. That
dualism (that is often found) is of course somewhat difficult to
describe in simple and short terms. The question is how this could be
described without introducing too much complexity. A different
approach could maybe be:

loadfile(file) returning (true,func) or (false, errordescription)

, which would describe the function quite adequately in my opinion
without too much "noise".

On the other hand I would not mind if the description format could be
somewhat more complex... I know that beginners are often easily
confused (sometimes by things that are simply beyond my
comprehension), but with time comes comprehension (or frustration of
course... ) and once one has mastered the basic things it becomes
simply annoying to reread things again and again just to figure out
again what the order of return values was. At least this is the case
for me...

Eike

2009/5/19 steve donovan <steve.j.donovan@gmail.com>:
> 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.
>