Koneki/LDT/Technical Discussions/Documentation Language

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.