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