Re: Defining APIs, best practices.

[steve donovan <steve.j.donovan@...>]

On Mon, Dec 17, 2012 at 8:39 AM, Dirk Laurie <dirk.laurie@gmail.com> wrote:
> That's why one should not have hundreds of tiny routines with names
> like that. `option{Enabled=true}` is unambiguous, extensible and uses
> up only one name. PiL 5.3.

Does require a different documentation strategy, however.  In such
cases I find myself doing something like this

--- sets the options
-- @lparam Options options
function mod.options(options)
...
end

---- Options table for mod.options
-- @field enabled ...
-- @field visible ...
...
-- @table Options

The Options table is a documentation artifact, but you end up with
much clearer (and more compact) documentation than the pseudo-Java
style.

(Can throw in extra type information if needed. With current LDoc
master one can say:

@bool enabled
@bool visible
@string name

and so forth, even for table definitions)

As for the dreaded {...},  such things do become important if you are
designing utility functions meant to be used by others. In that case,
it is not your job to decide on the optimization needs of the user.
Especially in functions which do not otherwise create tables as part
of their job, avoiding {...} is a useful practice, and as Phillip
points out, variable argument lists don't need it. Library functions
should give some indication of their resource demands, so that a user
feels safe using them in time-critical code.

steve d.