Revision as of 13:09, 16 July 2012

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.

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.