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

Difference between revisions of "LDT/Developer Area/Lua API Model 2"

< LDT
(TypeRef)
 
(26 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
=Lua API Model=
 
=Lua API Model=
  
The idea is to define a model of the external API of a Lua file, a way to express a contract.<br/>
+
The idea is to define a model of the external API of a Lua file.<br/>
This model will be used as input of:
+
This model will then be the main input of:
* a documentation generator,
+
* documentation generator,
 
* auto-completion engine,
 
* auto-completion engine,
* type checking at IDE side.
+
* type-checking.
 +
 
 +
The code relative to this model is based on lua and metalua, it is accessible [[LDT/MetaLua|here]].
 +
This model is build from [[LDT/User_Area/Documentation_Language|lua documentation language]] in code comments and later from lua code analysis. (see also : [[LDT/Developer_Area/Lua_Comment_Model|Lua Comment Model]])
  
 
====File====
 
====File====
A Lua file declare some global variable and types.
+
A Lua file declares some global variable and types.
A file return values (this is the value you get when you require this file)  
+
A file returns values (this is the values you get when you require this file)  
 
   
 
   
 
  file
 
  file
Line 19: Line 22:
  
 
====TypeDef====
 
====TypeDef====
There are some primitive type like string, number, boolean, any, nil, table, function (we must define it more precisely)<br/>
+
There are some primitive types like string, number, boolean, any, nil, table, function.<br/>
TypeDef allow users to define, theirs own types.<br/>
+
TypeDef allow users to define theirs own custom types.<br/>
There are 2 kind of typedef.
+
There are 2 kinds of typedef.
  
  typeDef=recordDef | functionDef
+
  typeDef = recordTypeDef | functionTypeDef
 
   
 
   
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)
+
A recordTypeDef can be used to define a record (a tuple), a module or an object. (It may be a sub-type of table)
  
 
  recordTypeDef
 
  recordTypeDef
 +
.string name
 
  .string shortdescription
 
  .string shortdescription
 
  .string description
 
  .string description
 
  .map(fieldname,item) fields
 
  .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.
+
A functionTypeDef allows to define a function. Most of the time, the type and the item holding it are merged.
Maybe, it could be usefull to named a type of function (for iterator perhaps)
+
It may be useful to name the type of function (for iterator perhaps)
  
  funtionTypeDef
+
  functionTypeDef
 +
.string name
 
  .string shortdescription
 
  .string shortdescription
 
  .string description
 
  .string description
Line 50: Line 55:
 
  (.boolean hidden)
 
  (.boolean hidden)
  
'''Remarks''': Hidden could be usefull, if we have a parameter we don't want to expose in the API<br/>
+
'''Remarks''': Hidden could be use when there is a parameter we don't want to expose in the API<br/>
'''Remarks''': Hidden and optional does not need to be in the 1st version.
+
'''Remarks''': hidden and optional does not need to be in the 1st version.
  
 
====Item====
 
====Item====
Line 57: Line 62:
 
  item
 
  item
 
  .string name
 
  .string name
 +
.string shortdescription
 
  .string description
 
  .string description
  .typeref type  
+
  .typeref type
  
'''Remarks''': Not sure an item has a name.<br/>
 
'''Remarks''': Perhaps, Item could be use for parameters..
 
  
 
====TypeRef====
 
====TypeRef====
It's a reference to a type. There 3 kind of reference.
+
It's a reference to a type. There are 3 kinds of reference.
  
 
  typeref: externaltyperef | internaltyperef |primitivetyperef
 
  typeref: externaltyperef | internaltyperef |primitivetyperef
Line 74: Line 78:
 
  internaltyperef
 
  internaltyperef
 
  .string typename
 
  .string typename
 
+
 
  primitivetyperef
 
  primitivetyperef
 
  .string typename
 
  .string typename
  
 
====Return values====
 
====Return values====
a values return has references to a type define in the Lua file.
+
A return value has references to a type defined in the Lua file.
a values return is a list of possible value to return.
+
A return value is a list of possible values to return.
  
e.g. if a function return a number or nil and err.
+
e.g. if a function returns a number, or nil and err.
you function will have 2 return values :
+
your function will have 2 return values :
- number a result
+
* <code>number</code> a result
- nil, err if an error occured
+
* <code>nil, err</code> if an error occured
  
 
  return
 
  return
Line 92: Line 96:
 
  (.defaultuse)
 
  (.defaultuse)
  
'''Remarks''': Perhaps we could have a defaultuse entry to define the return value the type checking should use.
+
'''Remarks''': Perhaps we could have a defaultuse entry to define the return value the type checker should use. At the moment, the first entry in types list is used to type the return value.
 
+
=Documentation Language=
+
+
--- --------------------------------------------------------------------------
+
-- short description.
+
-- long description
+
-- @file 
+
-- @return typeref, typeref description
+
--------------------------------------------------------------------------------
+
+
--- --------------------------------------------------------------------------
+
-- short description.
+
-- long descrition
+
-- @recordtype recordtypename
+
-- @field[type=typeref] field1name description
+
-- @field[type=typeref] field2name description
+
--------------------------------------------------------------------------------
+
+
-- ------------------------------------------------------------------------------
+
-- short description.
+
-- long descrition
+
-- @function[global] name
+
-- @param[type=typeref, optional=boolean, hidden=boolean] param1name description
+
-- @param[type=typeref, optional=boolean, hidden=boolean] param2name description
+
-- @return typeref,typeref decription
+
--------------------------------------------------------------------------------
+
+
-- ------------------------------------------------------------------------------
+
-- short description.
+
-- long descrition
+
-- @function[racoonmodule] name
+
-- @param[type=typeref, optional=boolean, hidden=boolean] name description
+
-- @return typeref,typeref decription
+
-- @return typeref,typeref decription
+
--------------------------------------------------------------------------------
+

Latest revision as of 12:35, 16 July 2014

Lua API Model

The idea is to define a model of the external API of a Lua file.
This model will then be the main input of:

  • documentation generator,
  • auto-completion engine,
  • type-checking.

The code relative to this model is based on lua and metalua, it is accessible here. This model is build from lua documentation language in code comments and later from lua code analysis. (see also : Lua Comment Model)

File

A Lua file declares some global variable and types. A file returns values (this is the values 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 types like string, number, boolean, any, nil, table, function.
TypeDef allow users to define theirs own custom types.
There are 2 kinds of typedef.

typeDef = recordTypeDef | functionTypeDef

A recordTypeDef can be used to define a record (a tuple), a module or an object. (It may be a sub-type of table)

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

A functionTypeDef allows to define a function. Most of the time, the type and the item holding it are merged. It may be useful to name the type of function (for iterator perhaps)

functionTypeDef
.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 use when there is 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 are 3 kinds of reference.

typeref: externaltyperef | internaltyperef |primitivetyperef

externaltyperef
.string modulename
.string typename

internaltyperef
.string typename

primitivetyperef
.string typename

Return values

A return value has references to a type defined in the Lua file. A return value is a list of possible values to return.

e.g. if a function returns a number, or nil and err. your 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 checker should use. At the moment, the first entry in types list is used to type the return value.

Back to the top