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.

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

Special comment with trimmed first line

Note: _markdown_ is supposed to be interpreted by Markdown.

---
-- Short description.
-- Long description

Special comment composed of short comments format

--[[-
 Short description.
 Long description
]]

Special comment with long comment format

--- Short description. Long description

Special comment in one line

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

Sample of type declaration

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

Sample of module declaration.

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

Sample of verbose module declaration

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

Sample of module returning custom type

Note: We used #string to refer to a primitive type.

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 short description.
-- Type long description
--
-- @type typename
-- @field #string fieldname Field description

Sample of field declaration in parent type block

---
-- Type short description.
-- Type long description
--
-- @type typename

---
-- Field description
--
-- @field [parent=#typename] #string fieldname 

Sample of field declaration in dedicated block

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.

Sample of function declaration

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.

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#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

Sample of type reference in a description

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.