[Date Prev][Date Next][Thread Prev][Thread Next]
- Subject: improving the Lua manual?
- From: Eike Decker <zet23t@...>
- Date: Tue, 19 May 2009 08:55:01 +0200
I frequently use the manual of Lua  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:
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  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 ;)