In Corona SDK, our various API calls are organized into libraries. This is just away of grouping similar functions. For instance:
facebook.login()
facebook.request()
facebook.logout()
Are all part of the facebook library. From your perspective the library name is just the name of the library with the API call separated by a period. There might be other libraries that functions of the same name, such as network.request(). By classifying them, we can have multiple “request” functions.
The “Type” entry tells you what type of items is being described. Most of the time, this will be “function” meaning it calls code and returns a value. Sometimes it will be “Number” or “String” meaning these are not runnable functions, but data values that your code can use. For instance: display.contentWidth doesn’t run code and get a result, it simply is a value your code can use, in this case a number.
Return Value should only be there for things that are a Type of “function”. Since function do work, they have to have a way to give that work back to you. This happens in one of two ways, the value is “returned” by the function:
local someNumber = tonumber( “10” )
In this case the function “tonumber” takes in a string that happens to have the letters 1 and 0 in it and returns an actual number 10. If the function returns a value, the “Return Value” will tell you what’s being returned. It could be “String”, “Number”, “Function”, “Table”, “Boolean”, “Userdata”. This lets you know what to expect to get back. Lua allows the function to return multiple things, so if you see our documentation saying:
Return Value: boolean, string
Then that function returns a true/false value and a string value.
Some functions don’t return anything like this. Usually because they can take too long to do the work requested. The network.request() is an example of this. Since we have no ideal how long it will take the web server to respond to the request, we don’t want to hold up your app from continuing to do things. These functions will have a “listener” function, some times referred to as a “call back function”. When the request completes, your code will be notified that the task is done by calling the function you passed in the “handle” the result.
But @rominggammer is right, start with some tutorials, look at some sample code. Dr. Burton’s book is a great starting point.
Rob