lua-users home
lua-l archive

[Date Prev][Date Next][Thread Prev][Thread Next] [Date Index] [Thread Index]

On Thu, Feb 16, 2012 at 11:02 AM, marbux <> wrote:
> flag candidates for improvement of function documentation, in
> particular with beginning coders and Lua newbies in mind.

This is true. Just having some LuaDoc-style function documentation is
not sufficient. There has to be fuller explanation ('narrative
documentation') and justification. I'm working on a little article and
I'll downplay some of the functional tricks that entertain me.

Generally newcomers come with expectations. They may be frustrated
that that they cannot just print out a table in the interactive
prompt.  Or they're accustomed to splitting strings and having
variables expanded in them. Lua string patterns are going to be new
and thus they are going to be scary (and even regexp-familiar people
need to adjust their expectations).

The most tricky kind of expectation is that every language must have a
'class' keyword.  That's a big stumbling block. Having something that
works as expected allows them to apply previous experience.

Well, we understand that these newcomers may put these training wheels
behind them later.. But a little bit of initial support is not a bad
thing, and most of that support is explanation and examples. A few
little functions could make a difference.

I don't think we're shopping for a standard library here; there's this
new sport called  'code golf'; this particular little exercise is more
like 'library golf' - see how much useful stuff we can pack into a few

steve d.