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


Oh that's cool.

One thing though - when I press ctrl-space and get the completion list, to the right of that in yellow is the detailed info about the particular function in the completion list - I don't know what the official name of that is, but I'll call that yellow box the "help-box".  When you press ctrl-space, or press tab to change focus to the completion-list box, the Markdown works as you describe.  But if you change focus to the help-box for a completion, either by clicking or tabbing, the Markdown gets lost and the word becomes normal font.

I should note I use a Mac OSX Lion, and I notice the screen flickers every time I move focus to the help-box, so this may be a Mac-specific thing (or even Lion-specific thing).

Should I open a bug on that, or is it a known issue?

-hadriel



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@xxxxxxxxxxx
http://dev.eclipse.org/mailman/listinfo/koneki-dev



Back to the top