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

[Hadriel Kaplan <hadrielk@xxxxxxxxx>]

Hi Simon,

Yup I forgot the leading #.  Works better now. :)

I made an Acme type because I was trying to figure out why it was having trouble with the arguments, and hoping that would fix it. 

But yes 'self' fixed it well (and is not a bad idea to have).

I'll keep the keyword collision problem in mind.  We use 'type' as the param name in a lot of our API documented functions, but that's an easy thing to replace with a script... a Lua script of course ;)

Thanks!

-hadriel

---

From: Simon Bernard <sbernard@xxxxxxxxxxxxxxxxxx>
To: Hadriel Kaplan <hadrielk@xxxxxxxxx>; General development dicussions for the Koneki project <koneki-dev@xxxxxxxxxxx>
Sent: Wednesday, February 29, 2012 8:44 AM
Subject: RE: [koneki-dev] How to comment-doc modules and object functions correctly

Hi,
I have noticed that there are a few some syntax problems in your sample:

1) There are errors with your @type declaration.
At the moment, you must add a '#' before the name. (Perhaps we should change this)

2) You defined a type #Acme in your Acme module, and this seems to be a mistake.
When you define a module with "@module Acme" it will automatically create a type with the name #Acme.
Maybe the type you wanted to define was @type #Weapon?

3) The good way to indicate a function is "invokable" (i.e. should be called with ":") is to name its first parameter 'self'
This will change the presentation in the html documentation, and will be used for autocompletion.
You're right in that there's a bug when e.g. weapon:checkWeapon is proposed in the autocompletion when it shouldn't, I have just fixed it.
Also, the fact that for checkWeapon() no potential arguments was suggested is another bug: you MUST NOT name your parameters 'type' (nor any other keyword of the documentation language). This needs to be fixed, but in the meantime you should avoid using keywords to name your elements or types.

4) Perhaps it is on purpose, but you don't seem to have any method in your module returning an instance of #WeaponType.

So the right syntax would be:

-------------------------------------------------------------------------------
-- The Acme table/module
-- @module Acme

-------------------------------------------------------------------------------
-- Acme stuff (mostly weapons)
-- @type #Weapon

-------------------------------------------------------------------------------
-- Weapon types
-- @type #WeaponType

-------------------------------------------------------------------------------
-- Checks if weapon is available from Acme
-- @function [parent=#Acme] checkWeapon
-- @param #WeaponType weaponType 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 weaponType The type to get
-- @return #Weapon The Acme weapon

-------------------------------------------------------------------------------
-- Kills the RoadRunner with weapon (unless you're a Cayote)
-- @function [parent=#Weapon] killRoadRunner
-- @param self
-- @return #boolean success or failure