Hello @Simeon. I’ve been thinking about the in-app documentation questions. In-app documentation is one of Codea’s strengths, and what you have done in 1.5 will take it to a new level.
###Codea Overview
I wondered if it would make sense to have a new, initial, chapter for the in-app reference called ‘Codea Overview’ (or something similar). It could cover certain matters that are common to one or more parts of the Codea API.
At the moment, ‘Getting Started’ (outside of the reference) covers: ‘Getting Started’, ‘Example Projects’, ‘Project Basics’, ‘Editor Basics’, ‘Editor Features’, ‘Codea Basics’ and ‘Troubleshooting’.
‘Codea Basics’ (namely, the various functions called by Codea) might be a candidate for a ‘Codea Overview’ in the reference.
Other candidates might be:
-
an explanation that Codea uses two different languages: Lua version 5.1, for most code, and the OpenGL ES Shading Language, for shaders. (The latter is stated in ‘Shader Overview’, but I think the former is not actually stated anywhere explicitly.)
-
an explanation that Codea uses the small number of Lua basic types (including number, string, boolean, function and table) together with userdata types specific to Codea. The userdata types could be listed, with related links to the parts of the reference where they are written up: body, image (codeaimage), soundbuffer (codeasoundbuffer), color, contact, joint, matrix, mesh, shader, touch, vec2, vec3, vec4.
You might add that the elements of Lua tables indexed by integers 1, 2, 3 to ‘n’ are referred to as ‘arrays’. (The term ‘array’ is used, for example, in the documentation of triangulate() and buffer.)
###Arguments, properties and results of functions
It seemed to me that the following were distinct things:
- the type of an argument, property or results of functions
- the acceptable range of values for an argument or property
- what the function does, precisely
Most arguments or properties are type ‘number’. In a ‘Codea Basics’ chapter, you might state: “If the type of an argument or property is not stated, it can be assumed to be number.” That would avoid a lot of references to ‘number’ elsewhere in the documentation.
For example, in the case of zLevel(z), the argument z could simply be described as “The amount of depth for future drawing operations. Use positive values to draw in front and negative values to draw behind.” without any reference to ‘number’ (or ‘float’, as is currently the case).
Take this code for example:
--
-- Arguments
--
function setup()
col = color(1000.5, 255, -127.5)
print(col) -- Output: (1000, 255, -127, 255)
fill(col)
print(fill()) -- Output: 1000 255 -127 255
strokeWidth(5)
end
function draw()
background(0)
ellipse(WIDTH/4, HEIGHT/2, 200)
ellipse(WIDTH * 3/4, HEIGHT/2, -200) -- Draws a square with a circular hole
end
Currently, the in-app reference says that color takes four ‘float’ values from 0 to 255 and that fill takes four ‘int’ values from 0 to 255.
It would be more accurate to say in both places that:
“Distinct colors of different opacities are represented by four integers with values from 0 to 255 (red, green, blue and alpha (opacity)).”
For color() it would be more accurate to say that “The function rounds arguments to the nearest integer”. For fill() it would be more accurate to say that “If an argument is less than 0 or greater than 255, it is treated as if it were 0 or 255, respectively.”
