Re: Is "scripting" truly Lua's future?

["Wesley Smith" <wesley.hoke@...>]

> Simplest method, use something like LuaDoc but have solid conventions for
> type names following the parameter names. This does require some discipline,
> as well as a sensible notation for Lua types; could be verbose, like 'list
> of string', 'map from string to number', etc.
>

This I think is incredibly important for code comprehension and code
reuse.  This past week, I've been working on extending LuaDoc to take
C++ files as input that hold my userdata classes and generate
module-like documentation.  The biggest stumbling block I had to
overcome was understanding the structure of various non-trivial data
types that have several layers of tables.  Nowhere in the
documentation or source code did I find a description of these
structures, which left me wondering about the arbitrariness of the
code.  Not that I'm trying to pick on LuaDoc, it just happens to be
what I'm working on right now.  A number of other Lua modules I've
encountered are equally opaque in this respect.

The trouble is that for someone to come into some code and be able to
understand what it's doing given a reasonable amount of effort
requires some bits of information that the Lua language just doesn't
provide and type information is probably the most glaring example.  I
understood what the LuaDoc code was doing on an initial pass, but it
took me quite an effort to figure out the details of how information
was being organized in the various data structures.  Without this
info, I couldn't extend it to meet my goals.  Essentially, I needed
some kind of schema for the table-based data structures.  I've given
up extending large pure Lua modules for this exact reason in the past.
 In this case, I ended up pretty-printing the table structures to a
log file so I could have concrete, verifiable info on their layout.

Despite these problems, I would still keep the Lua language how it is,
but I think authors of code that are meant to be widely used and
extended by others need to keep in mind some of the deficiencies of
the language in communicating what all is going on in a particular
chunk of code, and I would say documenting data structures is of
paramount importance.

wes