Koneki/LDT/Technical Discussions

Lua API Model

The idea is to define a model of the external API of a lua file, a way to express a contract.
This model will be used as input of:

• a documentation generator,
• auto-completion engine,
• type checking at ide side.

File

A lua file could define one module, list of global functions, global variables and types.

file
.string shortdescription
.string description
.module module
.list(function) globalfunctions
.list(var) globalvar
.list(type) globalvar

Questions?: should we support several modules by line (possible with module function())

Function

A function could define a list of parameter and a list of return values

function
.string name
.string shortdescription
.string description
.list(parameter) params
.list(return) returns

Questions?: how we know the function is a constructor ? Questions?: how could we know the type of variable if nth returned value could have more than one type ?

Parameter

a parameter has a reference to a type define in the lua file.

parameter

.string name
.ref type type
.string description
(.boolean optional)
(.boolean hidden)

Remarks: Hidden could be usefull, if we have a parameter we don't want to expose in the API Remarks: Perhaps hidden and optional does not need to be in the 1st version.

values Return

a values return has references to a type define in the lua file. a values return is a list of possible value to return.

e.g. if a function return a number or nil and err. you function will have 2 return values :

- number a result
- nil, err if an error occured

return
.list(ref type), types
.string description
(.defaultuse)

Remarks: Perhaps we could have a defaultuse entry to define the return value the type checking should use.

Variable

a Variable has a reference to a type define in the lua file.

var
.string name
.string shortdescription
.string description
.ref type type

Module

a module has a list of functions and fields

module
.string name
.string shortdescription
.string description
.list(function) functions
.list(var) fields

Type

a module has a list of methods, functions and fields

type
.string name
.string shortdescription
.string description
.list(function) methods 
.list(var) fields
(.list(function) functions)

Remarks: not sure we must separate functions and methods

Documentation syntax

This is a proposition of an explicit way to define the API via an luadoc like documentation syntax.
We thought that we should be able to express all the API only with documentation. If some information is missing, later, we could implement a way to find it by code analysing. The explicit documentation way will alway have the priority. This way you have the entire control on the API of your code.

--- 
-- Short Description of the Lua file.
-- Long Description blabla.

--- 
-- Short Description of the global function.
-- Long Description blabla.
-- @globalfunction
-- @name functionname
-- @param [type=typename,optional=false,hidden=false] parametername parameter description
-- @return [type=typename1] return description
-- @return [type=typename1,type=typename2] return description 

--- 
-- Short Description of the global var.
-- Long Description blabla.
-- @globalvar 
-- @name varname
-- @type typename

--- 
-- Short Description of the module.
-- Long Description blabla.
-- @module
-- @name modulename

--- 
-- Short Description of the module function.
-- Long Description blabla.
-- @modulefunction(modulename) 
-- @name functionname
-- @param [typename] parametername parameter description
-- @return [typename1,typename2] return description 

--- 
-- Short Description of the module field .
-- Long Description blabla.
-- @modulefield(modulename)
-- @name fieldname
-- @type typename

--- 
-- Short Description of the type.
-- Long Description blabla.
-- @typedef
-- @name typename

--- 
-- Short Description of the type method .
-- Long Description blabla.
-- @typemethod(typename)
-- @name fieldname
-- @param [type=typename,optional=false,hidden=false] parametername parameter description
-- @return [type=typename1] return description
-- @return [type=typename1,type=typename2] return description

--- 
-- Short Description of the type function .
-- Long Description blabla.
-- @typefunction(typename)
-- @name fieldname
-- @param [type=typename,optional=false,hidden=false] parametername parameter description
-- @return [type=typename1] return description
-- @return [type=typename1,type=typename2] return description

--- 
-- Short Description of the type field.
-- Long Description blabla.
-- @typefield(typename)
-- @name fieldname
-- @type typename