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

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 #typeref typedparamname description
-- @param untypedparamname description
-- @return #typeref, #typeref description

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

------------------------------------------------------------------------------
-- short description.
-- long description
-- @field[parent=#global] #typeref 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 the @module tag 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 such as string, table, boolean, ... In our syntax: #string, #table, #boolean, ...
  • internal: reference to types defined in the 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 until the next line starting with @. If no return is defined, the module will return a 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 the @type tag is found. Several @field clauses are allowed. They consist of the @field tag, followed by an optional type reference as described in the file comment section, then the field name and its textual description. Textual description is everything until next line starting with @.

Function comment block

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

Will be processed as a function comment block, when the @function tag is found. This tag 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 the 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 the @field tag is found. This tag 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 the referenced record type.

Back to the top