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 13:58, 12 December 2011 by Kkinfoo.sierrawireless.com (Talk | contribs) (Record comment block)

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 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 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 description
.typeref type 

Remarks: Not sure an item has a name.
Remarks: Perhaps, Item could be use for parameters..

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.

Documentation Language

Sample

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

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

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

--- ---------------------------------------------------------------------------
-- short description.
-- long descrition
-- @@function [#recordtyperef]
-- @param #typeref paramtypedname description
-- @param paramnottypedname description
-- @return typeref,typeref decription
------------------------------------------------------------------------------

Sample detailed explanation

File comment block

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

This section will be processed as file documentation block, when keyword @@file 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.

Record comment block

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

Will be processed as a record comment block, when keyword @@recordtype 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 @.

Global function comment block

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

This type of comment is detected when @@function is followed by [global]. Function name is mandatory. Several @param clauses are allowed. They consist of @param followed by an optional type, a parameter name and a description. Several @return clauses are allowed. They consist of @return followed by a list of types separated by comas and a textual description.

Local function comment block

------------------------------------------------------------------------------
-- short description.
-- long descrition
-- @@function [#recordtyperef]
-- @param #typeref paramtypedname description
-- @param paramnottypedname description
-- @return typeref,typeref decription
------------------------------------------------------------------------------

This type of comment require the @@function [#recordtyperef] sequence, where #recordtyperef is a local type. The other parameters are as in global functions.

Back to the top