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 aims to describe the API supplied by a file. It is strongly inspired by 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 all descriptions.
Special comments are handled only if they describe a concept.
Note: All -
at start of special comments are trimmed.
--------------------------------------------------------------------------------
-- Short description.
-- Long _markdown_ description
Note: _markdown_
is supposed to be interpreted by Markdown.
---
-- 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.
--------------------------------------------------------------------------------
-- Type short description.
-- Type 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. Here is the simpler way to declare a module.
--------------------------------------------------------------------------------
-- Module short description.
-- Module long description
--
-- @module modulename
When a module is declared, a type with its name is automatically created and returned. So, the following is equivalent to first module sample.
--------------------------------------------------------------------------------
-- Module short description.
-- Module long description
--
-- @module modulename
-- @return #modulename
---@type modulename
Note: We used #typename
to refer to a declared type, if you want to know more about it refer to type reference section.
In previous sample, you may wonder in which case it could be of any use to return manually a type for a module. It is useful when you want to return a type different from the one automatically created.
--------------------------------------------------------------------------------
-- Module short description.
-- Module long description
--
-- @module modulename
-- @return #string
Note: We used #string
to refer to a primitive type.
Field comment block
The field 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 short description.
-- Type long description
--
-- @type typename
-- @field #string fieldname Field description
---
-- Type short description.
-- Type long description
--
-- @type typename
---
-- Field description
--
-- @field [parent=#typename] #string fieldname
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.
--------------------------------------------------------------------------------
-- Function short description.
-- Function 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. There is a notation for this. It is based on types. So if you want to type a field or a function, they are several types of references available.
Primitive references
Refer to Lua primitive types, it is the type prefixed with #
.
-
#boolean
-
#nil
-
#number
-
#string
-
#table
Internal references
Enables to refer to types from current module, it is type name prefixed with #
.
-
#typename
will refer to type typename defined in current module.
External references
Enables to refer to a type from another module, it is targeted module name followed by internal reference which could be used in targeted module.
-
modulename#typename
will refer to type typename defined in module modulename. -
modulename#modulename
will refer to type modulename returned in module modulename.
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.