|
|
Line 1: |
Line 1: |
− | =Lua API Model=
| + | [[Koneki/LDT/Technical Discussions/Lua Model API]] |
− | | + | |
− | The idea is to define a model of the external API of a lua file, a way to express a contract.<br/>
| + | |
− | 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.<br/>
| + | |
− | 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
| + | |