Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

LDT/Developer Area/Lua API Model 2

< LDT
Revision as of 12:53, 2 February 2012 by Code.simonbernard.eu (Talk | contribs) (Sample)

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 declare some global variable and types. A file return values (this is the value you get when you require this file)

file
.string shortdescription
.string description
.map(typename, typedef) types
.map(varname,item) globalvars
.list(returnvalues) returns

TypeDef

There are some primitive type like string, number, boolean, any, nil, table, function (we must define it more precisely)
TypeDef allow users to define, theirs own types.
There are 2 kind of typedef.

typeDef=recordDef | functionDef

a recordTypeDef could be used to define a type of record(a tuple), a module or an object. (it's surely a subtype of table)

recordTypeDef
.string namme
.string shortdescription
.string description
.map(fieldname,item) fields

a functionTypeDef allow to define a type of function. Most of the time, the type and the item which hold it is merged. Maybe, it could be usefull to named a type of function (for iterator perhaps)

funtionTypeDef
.string name
.string shortdescription
.string description
.list(parameter) params
.list(returnvalues) returns

Parameter

parameter
.string name 
.typeref 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: Hidden and optional does not need to be in the 1st version.

Item

item
.string name
.string shortdescription
.string description
.typeref type


TypeRef

It's a reference to a type. There 3 kind of reference.

typeref: externaltyperef | internaltyperef |primitivetyperef

externaltyperef
.string modulename
.string typename

internaltyperef
.string typename

primitivetyperef
.string typename

Return values

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(typeref) types
.string description
(.defaultuse)

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

Documentation Language

Sample

------------------------------------------------------------------------------
-- short description.
-- long description
-- @module modulename
-- @return #primitivetyperef, my.module#externaltyperef, #internaltyperef description

-----------------------------------------------------------------------------
-- short description.
-- long descrition 
-- @type #recordtypename
-- @field #typeref fieldtypedname description
-- @field fieldnottypedname description

-----------------------------------------------------------------------------
-- short description.
-- long description
-- @function [parent=#global] functionname
-- @param #typref typedparamname description
-- @param untypedparamname description
-- @return #typeref, #typeref description

------------------------------------------------------------------------------
-- short description.
-- long descrition
-- @function [parent=#recordtyperef]
-- @param #typeref paramtypedname description
-- @param paramnottypedname description
-- @return #typeref,#typeref decription
------------------------------------------------------------------------------
-- short description.
-- long descrition
-- @field[parent=#global] #typref fieldname
------------------------------------------------------------------------------
-- short description.
-- long descrition
-- @field[parent=#recordtyperef] #typref fieldname

Sample detailed explanation

File comment block

------------------------------------------------------------------------------
-- short description.
-- long description
-- @module modulename 
-- @return #primitivetyperef, my.module#externaltyperef, #internaltyperef description
------------------------------------------------------------------------------

This section will be processed as module documentation block, when keyword @module is found. Several @return clauses are allowed. They are composed of a list of several type references. Those references represent types returned by this file. There are three kinds of type references:

  • primitive: reference to a built in type as string, table, boolean, ... In our syntax: #string, #table, #boolean, ...
  • internal: reference to types defined in current file. Such as #internaltyperef in previous sample.
  • external: reference to types defined in other modules. Such as : my.module#externaltyperef.

Textual description is everything till next line starting with @. If not return is defined, the module will return an record internal type named #modulename.

Record comment block

------------------------------------------------------------------------------
-- short description.
-- long descrition 
-- @type #recordtypename
-- @field #typeref fieldtypedname description
-- @field fieldnottypedname description
------------------------------------------------------------------------------

Will be processed as a type comment block, when keyword @type is found. Several @field clauses are allowed. They consist of the keyword @field followed by an optional type reference as described in the file comment section, then follow field name and textual description. Textual description is everything till next line starting with @.

Function comment block

------------------------------------------------------------------------------
-- short description.
-- long description
-- @function [parent=#global] functionname
-- @param #typref typedparamname description
-- @param untypedparamname description
-- @return #typeref,#typeref description
------------------------------------------------------------------------------

Will be processed as a function comment block, when keyword @function. This keyword is followed by a scope indicator:

  • [parent = #global]: to specify that this function will be stored in global environment.
  • [parent = #internalrecordtyperef]: where #internalrecordtyperef is a reference to a record type defined in current file. It allows to link this function to referenced record type.

Function name is optional. Several @param clauses are allowed. They consist of @param followed by an optional type, a parameter name and a textual description, which is everything until next line starting with a @. Several @return clauses are allowed. They consist of @return followed by a list of type references separated by comas and a textual description as previously described.

Back to the top