Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
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
            
            
          
        
      
    

    
  



Back to the top