Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Koneki/LDT/Technical Discussions/Documentation Language"
m (→Sample) |
|||
(4 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
+ | <span style="color:#B22222">'''(This page is deprecated, [[Koneki/LDT/User_Area/Documentation_Language| you could see the right one here]])'''</span> | ||
+ | |||
= Documentation Language = | = Documentation Language = | ||
Line 5: | Line 7: | ||
------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | ||
-- short description. | -- short description. | ||
− | -- long description @{# | + | -- long description @{modulename#recordtypename} |
-- @module modulename | -- @module modulename | ||
-- @return #primitivetyperef, my.module#externaltyperef, #internaltyperef description | -- @return #primitivetyperef, my.module#externaltyperef, #internaltyperef description | ||
Line 95: | Line 97: | ||
* '''[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 the 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. | ||
+ | |||
+ | ===Embedded type reference=== | ||
+ | |||
+ | ------------------------------------------------------------------------------ | ||
+ | -- short description. | ||
+ | -- long description @{modulename#recordtypename} | ||
+ | -- @module modulename | ||
+ | -- @return #primitivetyperef, my.module#externaltyperef, #internaltyperef description | ||
+ | |||
+ | Writing a textual description, you might want to reference a type or another element. In order to do so, you can use the embedded type reference notation. It is <code>@{x}</code>, where <code>x</code> is a type reference. Here is a list of available type references: | ||
+ | * '''#type''': where <code>type</code> is the name of a type defined in '''current file'''. | ||
+ | * '''#type.field''': where <code>field</code> is a field of defined <code>type</code>. | ||
+ | ** '''#(ty.pe).field''': when <code>ty.pe</code> name contains a dot. | ||
+ | * '''module#type''': where <code>type</code> is described in another <code>module</code>. | ||
+ | ** '''module#module''': where <code>module</code> is the type returned by another module. |
Latest revision as of 13:00, 12 September 2012
(This page is deprecated, you could see the right one here)
Contents
Documentation Language
Sample
------------------------------------------------------------------------------ -- short description. -- long description @{modulename#recordtypename} -- @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.
Embedded type reference
------------------------------------------------------------------------------ -- short description. -- long description @{modulename#recordtypename} -- @module modulename -- @return #primitivetyperef, my.module#externaltyperef, #internaltyperef description
Writing a textual description, you might want to reference a type or another element. In order to do so, you can use the embedded type reference notation. It is @{x}
, where x
is a type reference. Here is a list of available type references:
- #type: where
type
is the name of a type defined in current file. - #type.field: where
field
is a field of definedtype
.- #(ty.pe).field: when
ty.pe
name contains a dot.
- #(ty.pe).field: when
- module#type: where
type
is described in anothermodule
.- module#module: where
module
is the type returned by another module.
- module#module: where