Question about Popup Hints for Custom Functions

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

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!

@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.

@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.

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) = or function () print("@TODO") end
    -- Self created
    self.texture = image(self.size.x, self.size.y)
    self.meshSprite = MeshSprite(self.texture, {x = self.pos.x, y = self.pos.y, size = self.size})

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

@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.

@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.

@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)?

@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()
        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

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

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

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

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.