Jump to: navigation, search

Difference between revisions of "Koneki/LDT/Technical Discussions/Documentation Language"

(New page: = Documentation Language = == Sample == ------------------------------------------------------------------------------ -- short description. -- long description -- @module modulena...)
 
Line 53: Line 53:
  
  
This section will be processed as '''module documentation block''', when keyword <code>@module</code> is found.
+
This section will be processed as '''module documentation block''', when the keyword <code>@module</code> is found.
 
Several <code>@return</code> clauses are allowed. They are composed of a list of several type references.
 
Several <code>@return</code> clauses are allowed. They are composed of a list of several type references.
 
Those references represent types returned by this file.
 
Those references represent types returned by this file.
 
There are three kinds of type references:
 
There are three kinds of type references:
* '''primitive''': reference to a built in type as <code>string</code>, <code>table</code>, <code>boolean</code>, ... In our syntax: <code>#string</code>, <code>#table</code>, <code>#boolean</code>, ...
+
* '''primitive''': reference to a built-in type such as <code>string</code>, <code>table</code>, <code>boolean</code>, ... In our syntax: <code>#string</code>, <code>#table</code>, <code>#boolean</code>, ...
* '''internal''': reference to types defined in '''current file'''. Such as <code>#internaltyperef</code> in previous sample.
+
* '''internal''': reference to types defined in the '''current file'''. Such as: <code>#internaltyperef</code> in previous sample.
* '''external''': reference to types defined in '''other modules'''. Such as : <code>my.module#externaltyperef</code>.
+
* '''external''': reference to types defined in '''other modules'''. Such as: <code>my.module#externaltyperef</code>.
Textual '''description''' is everything till next line starting with <code>@</code>.
+
Textual '''description''' is everything until the next line starting with <code>@</code>.
If not return is defined, the module will return an record internal type named #modulename.
+
If no return is defined, the module will return a record internal type named #modulename.
  
 
=== Record comment block ===
 
=== Record comment block ===
Line 71: Line 71:
 
  -- @field fieldnottypedname description
 
  -- @field fieldnottypedname description
 
   
 
   
Will be processed as a '''type comment block''', when keyword <code>@type</code> is found.
+
Will be processed as a '''type comment block''', when the keyword <code>@type</code> is found.
Several <code>@field</code> clauses are allowed. They consist of the keyword <code>@field</code> followed by an optional type reference as described in the file comment section, then follow field name and textual description.
+
Several <code>@field</code> clauses are allowed. They consist of the keyword <code>@field</code> 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''' till next line starting with <code>@</code>.
+
Textual description is '''everything''' until next line starting with <code>@</code>.
  
 
===Function comment block===
 
===Function comment block===
Line 84: Line 84:
 
  -- @return #typeref,#typeref description
 
  -- @return #typeref,#typeref description
  
Will be processed as a function comment block, when keyword <code>@function</code>.
+
Will be processed as a function comment block, when the keyword <code>@function</code> is found.
 
This keyword is followed by a scope indicator:
 
This keyword is followed by a scope indicator:
 
* '''[parent = #global]''': to specify that this function will be stored in global environment.
 
* '''[parent = #global]''': to specify that this function will be stored in global environment.
 
* '''[parent = #internalrecordtyperef]''': where <code>#internalrecordtyperef</code> is a reference to a record type defined in current file. It allows to link this function to referenced record type.
 
* '''[parent = #internalrecordtyperef]''': where <code>#internalrecordtyperef</code> is a reference to a record type defined in current file. It allows to link this function to referenced record type.
Several <code>@param</code> clauses are allowed.  They consist of <code>@param</code> followed by an '''optional''' type, a parameter name and a textual description, which is everything until next line starting with a <code>@</code>.
+
Several <code>@param</code> clauses are allowed.  They consist of <code>@param</code> followed by an '''optional''' type, a parameter name and a textual description, which is everything until the next line starting with a <code>@</code>.
Several <code>@return</code> clauses are allowed. They consist of <code>@return</code> followed by a list of type references separated by comas and a textual description as previously described.
+
Several <code>@return</code> clauses are allowed. They consist of <code>@return</code> followed by a list of type references separated by comas, and a textual description as previously described.
  
 
===Field comment block===
 
===Field comment block===
Line 97: Line 97:
 
  -- @field[parent=#global] #typeref fieldname
 
  -- @field[parent=#global] #typeref fieldname
 
   
 
   
Will be processed as a field comment block, when keyword <code>@field</code>.
+
Will be processed as a field comment block, when the keyword <code>@field</code> is found.
 
This keyword is followed by a scope indicator:
 
This keyword is followed by a scope indicator:
 
* '''[parent = #global]''': to specify that this field will be stored in global environment.
 
* '''[parent = #global]''': to specify that this field will be stored in global environment.
* '''[parent = #internalrecordtyperef]''': where <code>#internalrecordtyperef</code> is a reference to a record type defined in current file. It allows to link this field to referenced record type.
+
* '''[parent = #internalrecordtyperef]''': where <code>#internalrecordtyperef</code> is a reference to a record type defined in current file. It allows to link this field to the referenced record type.

Revision as of 05:58, 10 February 2012

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

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