Howdy, Stranger!

It looks like you're new here. If you want to get involved, click one of these buttons!

Question about Popup Hints for Custom Functions

in Questions Posts: 33

I use and make a lot of dependencies in my workflow. I noticed that when I use built-in Codea functions/methods such as sprite(“Project:Image”, 0, 0, 100, 100) as I type along there is a hint that hovers above the code that says “x” “y” “width” “height”.

I was wondering if there is a certain commenting standard that you are using that allows for function hints. For example:

@usage: Function used to repeatedly print the same text to console.
@param text: Text to be printed
@param times: Number of times to be printed
function multiPrint(text, times)
    for i = 1, times do
        print(str)
    end
end

I always forget how to use my dependencies, so it would be convenient to have code hinting for my own code.

Thanks for you time!

Comments

  • SimeonSimeon Admin Mod
    Posts: 4,958

    @exomut I love this idea, probably need to prefix the @ annotations with -- to ensure that Lua doesn't parse them

    I have a fair bit of stuff before I can get to this but it's something I'd like to do after Codea 3.0 is out.

  • Posts: 33

    @simeon I totally forgot about commenting the @params out. Using -- or a block comment --[[ --]] would work really well. For my own projects, I have been trying to use a dumbed down version of LDoc guidelines

    I am really excited for what you have in store with Codea 3.0. I have been using Codea daily for work and for fun since I got it a couple weeks ago. Keep up the amazing work!

    Also, I added a bug report about Xcode to your Trello board. I wasn’t sure how you wanted your board organized so I added it to the bottom of the “Features” List and added the “Bug” label. My trello account is seth.

  • Posts: 33

    I just wanted to show an example of how I use comments with classes. I am wondering how others document their functions and classes.

    CustomButton = class()
    
    --[[
    @class CustomButton:            Creates a button with a Background image or background color and text
    @param table args:              Table of settings
        @args string text:              Button label text
        @args color textColor:          Button label text color
        @args float textPadding:        Padding from label's boundry box to text
        @args vec2 size:                Width and Height of button
        @args vec2 pos:                 X and Y position of button
        @args spriteMode spriteMode:    Sets the sprite mode
        @args blendMode blendMode:      Sets the blend mode
        @args image background:         Set to use an image as a background
        @args color color:              Sets the button color used if no background is supplied
        @args function run:             Adds a function to be called when the button is clicked
    --]]
    function CustomButton:init(args)
    
        if not args then args = {} end
    
        -- Set by args
        self.text = args.text or "Button"
        self.textColor = args.textColor or color(255)
        self.textPadding = args.textPadding or 0
        self.size = args.size or vec2(300, 100)
        self.pos = args.pos or vec2(WIDTH/2, HEIGHT/2)
        self.spriteMode = args.spriteMode or CENTER
        self.blendMode = args.blendMode or NORMAL
        self.background = args.background
        self.color = args.color or color(0)
        self.run = args.run or function () print("@TODO") end
    
        -- Self created
        self.texture = image(self.size.x, self.size.y)
        self:createTexture()
    
        self.meshSprite = MeshSprite(self.texture, {x = self.pos.x, y = self.pos.y, size = self.size})
    
    end
    
  • dave1707dave1707 Mod
    Posts: 7,605

    @exomut I very seldom comment my code. I make my code as simple as I can and use good variable names.

  • Posts: 33

    @dave1707 When you name your variables do you usually include the type in the name? Such as; strTitle. I have a hard time naming variables.

    I am still pretty new to programming.

  • dave1707dave1707 Mod
    Posts: 7,605

    @exomut I don't add a type, the name is usually enough. If you're just starting coding, then do whatever makes it easy for you. If you write a lot of different programs then adding comments will make things easier when you have to go back and make updates.

  • Posts: 33

    @dave1707 When you create a class that has a Class:init() that has a lot of settings how do you handle all of the different variables? Do you use Class:init(args) or do you use Class:init(x, y) and then set the rest of the variables later after calling class = Class(100, 100)?

  • dave1707dave1707 Mod
    Posts: 7,605

    @exomut Again, things will depend on how comfortable you are with your code. How I write code might not be how you want to write code. The more programs you write, the more you'll get into a routine that's comfortable to you. Here's an example of some ways to initialize a class with several variables. You might not like any of these and come up with your own way. I added a bunch of comments to give you an idea of where they can be.

    function setup()
        t1=test1(
            100, -- comment
            200, -- comment
            300, -- comment
            400, -- comment
            500, -- comment
            600, -- comment
            700  -- comment
            )
    
        t2=test2()  -- comment
        t2.var1=100 -- comment
        t2.var2=200 -- comment
        t2.var3=300 -- comment
        t2.var4=400 -- comment
        t2.var5=500 -- comment
        t2.var6=600 -- comment
        t2.var7=700 -- comment
    
        t3=test3(100,200,300,400,500,600,700)   -- comment
    
        print(t1.var3)
        print(t2.var5)
        print(t3.var7)
    end
    
    test1=class()   -- comment
    
    function test1:init(v1,v2,v3,v4,v5,v6,v7)
        self.var1=v1    -- comment
        self.var2=v2    -- comment
        self.var3=v3    -- comment
        self.var4=v4    -- comment
        self.var5=v5    -- comment
        self.var6=v6    -- comment
        self.var7=v7    -- comment
    end
    
    test2=class()   -- comment
    
    function test2:init()
        self.var1=0    -- comment
        self.var2=0    -- comment
        self.var3=0    -- comment
        self.var4=0    -- comment
        self.var5=0    -- comment
        self.var6=0    -- comment
        self.var7=0    -- comment
    end
    
    test3=class()   -- comment
    
    function test3:init(v1,v2,v3,v4,v5,v6,v7)
        self.var1=v1    -- comment
        self.var2=v2    -- comment
        self.var3=v3    -- comment
        self.var4=v4    -- comment
        self.var5=v5    -- comment
        self.var6=v6    -- comment
        self.var7=v7    -- comment
    end
    
  • Posts: 430

    Documenting functions like @exomut says is quite standard and very good practice. I agree it would be great if Codea could use this to add hints. I have a similar difficulty in remembering how all the functions in all my libraries are defined.

    "Simple" code does not always mean "short" code. I tend to write reusable code, which often means that I have lots of functions that I don't use every time I include a dependency and so don't always recall easily how I implemented a particular function.

Sign In or Register to comment.