Re: [koneki-dev] How to comment-doc modules and object functions correct

[Kevin KIN-FOO <kkinfoo@xxxxxxxxxxxxxxxxxx>]

First of all,
Thanks for the feedback.
I think that when completion is triggered with ':', available methods are shown removing first parameter considered as 'self'. Check actual parameter type might be a nice enhancement. We'll have to determine where to position this feature in our backlog.
As far I'm concerned your syntax is perfect.
Cheers
Le 28/02/2012 09:06, Hadriel Kaplan a écrit :

Howdy,

Let's say you have a module with a function that returns an object (well, a Lua userdata type that has functions to call using 'self' or the colon ':' notation).  But it also has functions that take other initial parameters (i.e., normal functions of the module).

For example:

-------------------------------------------------------------------------------

-- The Acme table/module

-- @module Acme

-------------------------------------------------------------------------------

-- Acme stuff (mostly weapons)

-- @type Acme

-------------------------------------------------------------------------------

-- Weapon types

-- @type WeaponType

-------------------------------------------------------------------------------

-- Checks if weapon is available from Acme

-- @function [parent=#Acme] checkWeapon

-- @param #WeaponType type The type of weapon to check for

-- @param #number quantity The number of weapons to check for

-- @return #boolean True if the weapon is available, else false

-------------------------------------------------------------------------------

-- Gets weapons to kill the RoadRunner

-- @function [parent=#Acme] getWeapon

-- @param #WeaponType type The type to get

-- @return #Acme The Acme weapon

-------------------------------------------------------------------------------

-- Kills the RoadRunner with weapon (unless you're a Cayote)

-- @function [parent=#Acme] killRoadRunner

-- @param #Acme weapon

-- @return #boolean success or failure

So you do this:

local weapon = Acme.getWeapon()

weapon:<ctrl-space>

<ctrl-space> now shows checkWeapon() as a potential completion, without any potential arguments (though the param 'quantity' appears in the help-box).

But it shouldn't show up at all, because the first argument/param of checkWeapons is not a #Acme.

Oddly, getWeapon() doesn't show up as a completion, which is correct but I was surprised, since it does show checkWeapon().

Am I doing the right comment-doc syntax/model?

Sorry for the newbie questions. :(

-hadriel