|
|
| (12 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| − | =Lua API Model= | + | <span style="color:#B22222">'''(This page is deprecated, [[Koneki/LDT#Developer_Area| you could see the right one]])'''</span> |
| | | | |
| − | The idea is to define a model of the external API of a lua file, a way to express a contract.<br/>
| + | *[[Koneki/LDT/Technical Discussions/Documentation Language|Documentation Language ]]<br/> |
| − | This model will be used as input of:
| + | *[[Koneki/LDT/Technical Discussions/Lua API Model_2|Lua API Model Description ]]<br/> |
| − | * a documentation generator, | + | *[[Koneki/LDT/Technical Discussions/User Assistance|User Assistance ]]<br/> |
| − | * 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
| + | |
