From: Benjamin Cabé <bcabe@xxxxxxxxxxxxxxxxxx>
To: General development dicussions for the Koneki project
<koneki-dev@xxxxxxxxxxx>
Sent: Tuesday, February 28, 2012 4:33 AM
Subject: Re: [koneki-dev] How to comment-doc modules and object functions correctly
Hadriel, could you please open a bug so as we do not forget to address the
issue?
On a side note, when you write things like
-- @return #boolean True if the weapon is available, else false
do not forget that you can make the documentation look better using
Markdown, for example:
-- @return #boolean `true` if the weapon is available, else `false`
Cheers,
Benjamin
Benjamin Cabé :: Open Source Manager
SIERRA WIRELESS :: AirVantage Business Unit
Main +33 5 61 00 52 90 :: Direct +33 5 61 00 06 41 :: Fax +33 5 61
00 51 46
Lake Park :: Zac de l'Hers - Allée du Lac - BP 87216 :: 31672 Labège
Cedex, France
BCabe@xxxxxxxxxxxxxxxxxx ::
www.sierrawireless.com<http://www.sierrawireless.com/>
________________________________________________________________________
De : Kevin Kin-foo <
kkinfoo@xxxxxxxxxxxxxxxxxx>
Répondre à : General development dicussions for the Koneki project
<
koneki-dev@xxxxxxxxxxx>
Date : Tue, 28 Feb 2012 00:38:09 -0800
À : "
koneki-dev@xxxxxxxxxxx" <
koneki-dev@xxxxxxxxxxx>
Objet : Re: [koneki-dev] How to comment-doc modules and object functions
correctly
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
_______________________________________________
koneki-dev mailing list
koneki-dev@xxxxxxxxxxxhttp://dev.eclipse.org/mailman/listinfo/koneki-dev