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.
LDT/User Area/Documentation Language
This documentation language has been developed as part of Koneki, it is written directly in the source file, like LDoc and Javadoc. Information given with this language is parsed by LDT and supply advanced features such as code completion and documentation view. Before diving into syntax, it is time to enumerate the underlying concepts, knowing them will enable you to write documentation more efficiently.
Contents
Comments
Special comments
First of all, only special comments are parsed as part of Lua documentation. To mark your comment as special, just start it with ---
.
Special comments can contain a short and an long description. The short description start at the beginning of the comment and continue till .
or ?
. The long description is the text coming after. By the way, markdown is supported in both descriptions.
Comments won't be handled if they typed.
Note: All -
at start of special comments are trimmed.
--------------------------------------------------------------------------------
-- Short description.
-- Long description
---
-- Short description.
-- Long description
--[[-
Short description.
Long description
]]
--- Short description. Long description
Type comment block
A type comment block is a special comment with a type declaration with @type
key word followed by desired type name.
--------------------------------------------------------------------------------
-- Short description.
-- Long description
--
-- @type typename
Module comment block
Denoted by @module
keyword and followed by a module name, a module is the type described in a file. This is why there should be only one module declaration per file. In Lua, a module could return several values. Our documentation language allows it with @return
keyword. Here is a verbose sample.
--------------------------------------------------------------------------------
-- Short description.
-- Long description
--
-- @module typename
-- @return #typename
---@type typename
Note: We used #typename
to refer to a declared type, if you want to know more about it refer to type reference section.
--------------------------------------------------------------------------------
-- Short description.
-- Long description
--
-- @module typename
-- @return #typename, #anothertypename
---@type typename
---@type anothertypename
If you find it is too much to write, there is a shortcut. When a module is declared, a type with its name is automatically created and returned. So, to following is equivalent to first module sample.
--------------------------------------------------------------------------------
-- Short description.
-- Long description
--
-- @module typename
Field comment block
The field module block represents a field of a type. It is possible to declare one with @field
key word followed by field name and optional description.
There are two ways of defining a field, in its parent block type or in a separate documentation block where you have to mention field parent.
--------------------------------------------------------------------------------
-- @type typename
-- @field fieldname Field description
---@field [parent=#typename] anotherfieldname Field Description
Function comment block
The function comment block has to be attached to a type. Its keyword is @function
. A function can have several parameters denoted by keyword @param
, they can be typed or not and have an optional description. Several types of @return
are also possible.
--------------------------------------------------------------------------------
-- Short description.
-- Long description
--
-- @function [parent=#typename] functionname
-- @param self
-- @param #string parametername Parameter description
-- @return #number
-- @return Description of returned value
-- @return #nil, #string Nil and error message.
References
Type references
In comments blocks it is often needed to refer to a type or a field. There is a notation for this. It is based on types. So if you want to refer to a field or a function, you must mention its parent type. They are several types of references.
Primitive references
Refer to Lua primitive types, it is the type prefixed with #
.
-
#boolean
-
#nil
-
#number
-
#string
-
#table
Internal references
Enables to refer to element from current module, it is element name prefixed with #
.
-
#typename
will refer to type typename defined in current module. -
#(typename).fieldname
will refer to fieldname field with typename parent type defined in current module. -
#(typename).functionname
will refer to functionname function with typename parent type defined in current module.
External references
Enables to refer to element from another module, it is targeted module name followed by internal reference which could be used in targeted module.
-
modulename#modulename
will refer to type modulename returned in module modulename. -
modulename#typename
will refer to type typename defined in module modulename. -
modulename##(typename).fieldname
will refer to fieldname field with typename parent type defined in modulename module. -
modulename##(typename).functionname
will refer to functionname function with typename parent type defined in modulename module.
In description
It is possible to reference a type in a description. You just have to surround a type reference with @{}
.
--------------------------------------------------------------------------------
-- Short description and reference to @{io#(io).flush}.
--
-- @function [parent=#typename] functionname
Limitations
Identifiers
Due to our way of parsing, is not possible to use tag names as identifiers. So assume that the following identifiers are reserved:
- field
- function
- module
- param
- return
- type
Markdown
Markdown allows reusable element. As each description is parsed separately, you cannot reuse an element from another description.