Re: Defining APIs, best practices.

[Jorge Visca <xxopxe@...>]

On Sat, Dec 15, 2012 at 6:02 AM, Dirk Laurie <dirk.laurie@gmail.com> wrote:

True or false:

1. Most API's written in Lua have no more than one user,
    viz. the author.

I'm about to get one user besides me for an API, that's why am asking. :)

 

All in all, if i accept parameters for enable(), i don't see a way around the enable() being enable(nil) conundrum... set_enabled() shows the same misbehavior.

The parameterless version with enable() / disable() / is_enabled() is ok if verbose, but then again it sidesteps the problem: if i have the enable-flag in some variable, the user have to do a if/then/else to call the right method. Well, at least the user knows the semantics of the flag so he can build the right if/then/else... An probably that's a moot point if the method is called most times un-compossed, like always enable or disable.

I think i'll stick with the following pattern:

gps_power(v)  --avoid verbs in method name

   if v==true then

      --enable

   elseif v==false

      --disable

   elseif v~=nil 

      error()

   end

   return current

end

Documented as "true enables, false disables, nil keeps as is. Returns the status as set". I expect it to be used with a "true" or "false" passed directly, not as result of some previous computation. enable()/disable()/is_ernabled() would work just as good in this case, but like this i have only one method vs 3.

I will look into using metamethods, that looks actually nice. I'll look how nice it plays with LDoc generated documentation, tough...

Thanks for allthe input.

Jorge