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.
Difference between revisions of "LDT/Developer Area/Lua API Model 2"
m (→TypeRef) |
(→Documentation Language) |
||
| Line 95: | Line 95: | ||
=Documentation Language= | =Documentation Language= | ||
| − | + | ||
| − | --- -------------------------------------------------------------------------- | + | --- --------------------------------------------------------------------------- |
-- short description. | -- short description. | ||
-- long description | -- long description | ||
| − | -- @file | + | -- @@file |
| − | -- @return | + | -- @return #primitivetyperef, my.module#externaltyperef, #internaltyperef description |
| − | + | ------------------------------------------------------------------------------ | |
--- -------------------------------------------------------------------------- | --- -------------------------------------------------------------------------- | ||
-- short description. | -- short description. | ||
-- long descrition | -- long descrition | ||
| − | -- @recordtype recordtypename | + | -- @@recordtype #recordtypename |
| − | -- @field | + | -- @field #typeref fieldtypedname description |
| − | -- @field | + | -- @field fieldnottypedname description |
| − | + | ------------------------------------------------------------------------------ | |
| − | + | --- -------------------------------------------------------------------------- | |
-- short description. | -- short description. | ||
-- long descrition | -- long descrition | ||
| − | -- @function[global] | + | -- @@function [global] functionname |
| − | -- @param | + | -- @param paramtypedname description |
| − | -- @param | + | -- @param paramnottypedname description |
-- @return typeref,typeref decription | -- @return typeref,typeref decription | ||
| − | + | ------------------------------------------------------------------------------ | |
| − | + | --- --------------------------------------------------------------------------- | |
-- short description. | -- short description. | ||
-- long descrition | -- long descrition | ||
| − | -- @function[ | + | -- @@function [#recordtyperef] |
| − | -- @param | + | -- @param #typeref paramtypedname description |
| − | -- @ | + | -- @param paramnottypedname description |
-- @return typeref,typeref decription | -- @return typeref,typeref decription | ||
| − | + | ------------------------------------------------------------------------------ | |
Revision as of 12:27, 5 December 2011
Contents
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
--- --------------------------------------------------------------------------- -- 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 descrition -- @@function [global] functionname -- @param paramtypedname description -- @param paramnottypedname description -- @return typeref,typeref decription ------------------------------------------------------------------------------ --- --------------------------------------------------------------------------- -- short description. -- long descrition -- @@function [#recordtyperef] -- @param #typeref paramtypedname description -- @param paramnottypedname description -- @return typeref,typeref decription ------------------------------------------------------------------------------