improving the Lua manual?

[Eike Decker <zet23t@...>]

Hi

I frequently use the manual of Lua [1] to write my code. The
documentation is already good, but I have a suggestion for improvement
for the Lua function descriptions - or at least I want to point out
what problem I am having with it when using it.

The function descriptions have right now the function name and its
arguments as header, for example:

"math.sin (x)

Returns the sine of x (assumed to be in radians)."

The header information contains in most cases all the information for
me to use the function - with one exception: The returned values. This
is always a bit tedious because I have to read the whole description
of the function to figure out what it returns and in a lot of cases
the description is much longer and the information about the return
values are scattered within the description. Sometimes I only want to
know which returned value is in which position and yet I need to
reread a whole paragraph to figure it out again.

I would thus suggest to include the returned values within the header
as well, similar like the arguments are described. I included such
information within an API that I wrote [2] this way:

"pos (actornode self, [float x,y,z])
    returns: ([float x,y,z])
    sets/gets position "

A shorter form that I also like could be:

"(number) math.sin (x)"

where "(number)" refers to the returned value. For another function
this could look like this:

"(success, [err/···]) coroutine.resume (co [, val1, ···])"

other variants could be to write the returned values after the
argument values, i.e.

"coroutine.resume (co [, val1, ···]) returning (success, [err/···]) "

I know that this is probably not an important issue but since I am
regularly reminded of this when I try to figure out the returned
values of a function, I decided this morning to bring this up. The
multiple return values are one of the key features that I enjoy the
most when using Lua. I would really like to see the documentation to
value this feature more by highlighting it stronger ;)

Greetings,
Eike

[1]: http://www.lua.org/manual/5.1/manual.html
[2]: http://luxinia.de/doc/frames/actornode.html#pos