Jump to: navigation, search

Koneki/LDT/Technical Discussions/Documentation Language

< Koneki‎ | LDT‎ | Technical Discussions
Revision as of 15:13, 9 February 2012 by Sbernard.sierrawireless.com (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

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.

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.

Field comment block

------------------------------------------------------------------------------
-- short description.
-- long description
-- @field[parent=#global] #typeref fieldname

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

  • [parent = #global]: to specify that this field 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 field to referenced record type.