Our documentation language introduce some concepts which may not be described explicitly in Lua, but help for API description and tooling.

+

Our documentation language introduce some concepts which may not be described explicitly in Lua, but help to defined the contract between the library provider and the user.

== Type ==

== Type ==

−

This is the most important one. A ''type'' is a set of values, accessible through keys. Theses keys can point to functions or scalar values. A ''type'' is the representation of a table returned by a Lua module.

+

This is the most important one. A compound ''type'' is a set of values, accessible through fields. It is not a primitive type like <code>string</code>, <code>number</code> or <code>nil</code>. Theses fields can point to functions, primitive values or other compound types.

+

+

It is the way to explicitly ensure the structure of a Lua table.

== Module ==

== Module ==

−

It is simply the ''type'' returned by a file.

+

It is ''requireable'' entity - you can use the <tt>require</tt> function on it- <br>

+

This concept allow you to express :

+

* which ''type'' will be return by the <tt>require</tt> function for your module,

+

* which new global variables will be available after your module was loaded.<br>

+

Most of the time people refer to the returned type instance as module.

== Field ==

== Field ==

−

It is '''always''' a key of ''type'', as a field of a table returned by a module in Lua.

+

It is '''always''' a field of a ''type''. This is the way to ensure the presence of a value in a table which implement a type.

== Function ==

== Function ==

−

It is a special type of ''field'' which can have parameters and return values, just as Lua functions.

+

It is a special kind of ''field'' which can have parameters and return values, just as Lua functions. Both parameters and returned values can be typed. This concept allow to express a contract about which parameters suit a function and expected outputs.

== Global ==

== Global ==

−

In Lua you can affect and read globals at anytime. To handle those cases, the predefined type ''global'' is available. It is a reserved type which will be available everywhere, enabling you to attach field and function to it.

+

When a module is required, it could modify the global environment. To handle those cases, the predefined type ''global'' is available. It is a reserved type which will be available everywhere, enabling you to attach field and function to it.

+

This is a way to express the creation of new global variables when module is loaded.

+

+

== Type references ==

+

+

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, a function parameter or returned value, they are several kinds of references available.

+

+

=== Primitive references ===

+

+

Refer to Lua ''primitive types'', it is the type prefixed with <code>#</code>.

+

+

* <code>#boolean</code>

+

* <code>#nil</code>

+

* <code>#number</code>

+

* <code>#string</code>

+

* <code>#table</code>

+

+

=== Internal references ===

+

+

Enables to refer to types defined in current module, it is type name prefixed with <code>#</code>.

+

+

* <code>#typename</code> will refer to type ''typename'' defined in current module.

+

+

=== External references ===

+

+

Enables to refer to a type defined in another module, it is targeted module name followed by internal reference which could be used in targeted module.

* <code>modulename#modulename</code> will refer to type ''modulename'' returned in module ''modulename''.

= Comments =

= Comments =

Line 33:

Line 67:

First of all, only ''special comments'' are parsed as part of Lua documentation. To mark your comment as special, just start it with <code>---</code>.

First of all, only ''special comments'' are parsed as part of Lua documentation. To mark your comment as special, just start it with <code>---</code>.

−

Special comments can contain a short and an long description. The ''short description'' start at the beginning of the comment and continue till <code>.</code> or <code>?</code>. The ''long description'' is the text coming after. By the way, [http://fr.wikipedia.org/wiki/Markdown Markdown] is supported in ''all'' descriptions.

+

Special comments can contain a short and an long description. The ''short description'' start at the beginning of the comment and continue till <code>.</code> or <code>?</code>. The ''long description'' is the text coming after. By the way, [http://en.wikipedia.org/wiki/Markdown Markdown] is supported in ''all'' descriptions.

Special comments are handled '''only if they describe a [[Koneki/LDT/Technical_Documentation/Documentation_Language#Concepts|concept]]'''.

Special comments are handled '''only if they describe a [[Koneki/LDT/Technical_Documentation/Documentation_Language#Concepts|concept]]'''.

Line 45:

Line 79:

</pre></code>

</pre></code>

<center><small>Special comment with trimmed first line </small></center>

<center><small>Special comment with trimmed first line </small></center>

−

'''Note''': <code>_markdown_</code> is supposed to be interpreted by [http://fr.wikipedia.org/wiki/Markdown Markdown].

+

'''Note''': <code>_markdown_</code> is supposed to be interpreted by [http://en.wikipedia.org/wiki/Markdown Markdown].

<code><pre>

<code><pre>

Line 104:

Line 138:

</pre></code>

</pre></code>

<center><small>Sample of verbose module declaration</small></center>

<center><small>Sample of verbose module declaration</small></center>

−

'''Note''': We used <code>#typename</code> to refer to a declared type, if you want to know more about it refer to [[Koneki/LDT/Technical_Documentation/Documentation_Language#References|type reference section]].

+

'''Note''': We used <code>#modulename</code> to refer to a declared type, if you want to know more about it refer to [[Koneki/LDT/Technical_Documentation/Documentation_Language#Type_references|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.

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.

Line 121:

Line 155:

== Field comment block ==

== Field comment block ==

−

The field block represents a [[Koneki/LDT/Technical_Documentation/Documentation_Language#Field|field of a type]]. It is possible to declare one with <code>@field</code> keyword followed by optional type, field name and optional description.

+

The field block represents a [[Koneki/LDT/Technical_Documentation/Documentation_Language#Field|field of a type]]. It is possible to declare one with <code>@field</code> keyword followed by optional [[Koneki/LDT/Technical_Documentation/Documentation_Language#Type_references|type reference]], 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.

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.

Line 151:

Line 185:

== Function comment block ==

== Function comment block ==

−

The function comment block has to be attached to a type. Its keyword is <code>@function</code>. A [[Koneki/LDT/Technical_Documentation/Documentation_Language#Function|function]] can have several parameters denoted by keyword <code>@param</code>, they can be optionally typed and have an optional description. Several <code>@return</code> cases are also possible, but ''LDT inference -which is used for code assistance- only handles the fist one''. As Lua functions allow to return several values at once, it is possible to ''define several returned values'' per <code>@return</code> markup. <br/>

+

The function comment block has to be attached to a type. Its keyword is <code>@function</code>. A [[Koneki/LDT/Technical_Documentation/Documentation_Language#Function|function]] can have several parameters denoted by keyword <code>@param</code>, they can be optionally typed with a [[Koneki/LDT/Technical_Documentation/Documentation_Language#Type_references|type reference]] and have an optional descriptions. Several <code>@return</code> cases are also possible, but ''LDT inference -which is used for code assistance- only handles the first one''. As Lua functions allow to return several values at once, it is possible to ''define several returned values'' per <code>@return</code> markup. Returned values can be optionally typed using a [[Koneki/LDT/Technical_Documentation/Documentation_Language#Type_references|type reference]].<br/>

'''Note''': If the first <code>@param</code> is called ''self'', LDT will show completion proposal without this parameter but using <code>:</code> invocation operator.

'''Note''': If the first <code>@param</code> is called ''self'', LDT will show completion proposal without this parameter but using <code>:</code> invocation operator.

Line 167:

Line 201:

</pre></code>

</pre></code>

<center><small>Sample of function declaration</small></center>

<center><small>Sample of function declaration</small></center>

+

+

'''Note''': It is also possible to document function for types which name contains <code>"."</code>.

<center><small>Sample of function declaration related to a type which name contains <code>"."</code></small></center>

== Global comment block ==

== Global comment block ==

−

To declare a function or a field as ''[[Koneki/LDT/Technical_Documentation/Documentation_Language#Global|global]]'', you just have to attach it to the <code>global</code> type.

+

To declare a function or a field with a [[Koneki/LDT/Technical_Documentation/Documentation_Language#Type_references|type reference]] as ''[[Koneki/LDT/Technical_Documentation/Documentation_Language#Global|global]]'', you just have to attach it to the <code>global</code> type.

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 kinds of references available.

+

--- Move the rectangle

+

-- @function [parent=#rectangle] move

+

-- @param #rectangle self

+

-- @param #number x

+

-- @param #number y

+

function R.move(self,x,y)

+

self.x = self.x + x

+

self.y = self.y + y

+

end

−

=== Primitive references ===

+

--- Create a new rectangle

+

-- @function [parent=#geometry] newRectangle

+

-- @param #number x

+

-- @param #number y

+

-- @param #number width

+

-- @param #number height

+

-- @return #rectangle the created rectangle

+

function M.newRectangle(x,y,width,height)

+

local newrectangle = {x=x,y=y,width=width,height=height}

+

+

-- set to new rectangle the properties of a rectangle

+

setmetatable(newrectangle, {__index = R})

+

return newrectangle

+

end

−

Refer to Lua ''primitive types'', it is the type prefixed with <code>#</code>.

+

return M

+

</pre></code>

+

<center><small>Sample of documented in-module type</small></center>

−

* <code>#boolean</code>

+

= Short references =

−

* <code>#nil</code>

+

−

* <code>#number</code>

+

−

* <code>#string</code>

+

−

* <code>#table</code>

+

−

+

−

=== Internal references ===

+

−

+

−

Enables to refer to types defined in current module, it is type name prefixed with <code>#</code>.

+

−

+

−

* <code>#typename</code> will refer to type ''typename'' defined in current module.

+

−

+

−

=== External references ===

+

−

+

−

Enables to refer to a type defined in another module, it is targeted module name followed by internal reference which could be used in targeted module.

* <code>modulename#modulename</code> will refer to type ''modulename'' returned in module ''modulename''.

+

−

+

−

== Short references ==

+

It is way to reference a types and their fields ''in a textual description''. You just have to surround a type reference with <code>@{}</code>. You can reference a types and their fields, functions are handled as a specific type of fields.

It is way to reference a types and their fields ''in a textual description''. You just have to surround a type reference with <code>@{}</code>. You can reference a types and their fields, functions are handled as a specific type of fields.

Line 245:

Line 309:

* Reference to types

* Reference to types

** <code>@{#typename}</code> will refer to type ''typename'' defined in current module.

** <code>@{#typename}</code> will refer to type ''typename'' defined in current module.

−

** <code>@{#modulename}</code> equivalent to previous notation, as a module is the type returned by a file.

+

** <code>@{modulename}</code> will refer to module named ''modulename''.

Revision as of 10:07, 10 June 2013

This documentation language has been developed as part of Koneki, its main goal is to describe the API supplied by a file. It is strongly inspired by LDoc. 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.

Concepts

Our documentation language introduce some concepts which may not be described explicitly in Lua, but help to defined the contract between the library provider and the user.

Type

This is the most important one. A compound type is a set of values, accessible through fields. It is not a primitive type like string, number or nil. Theses fields can point to functions, primitive values or other compound types.

It is the way to explicitly ensure the structure of a Lua table.

Module

It is requireable entity - you can use the require function on it-
This concept allow you to express :

which type will be return by the require function for your module,

which new global variables will be available after your module was loaded.

Most of the time people refer to the returned type instance as module.

Field

It is always a field of a type. This is the way to ensure the presence of a value in a table which implement a type.

Function

It is a special kind of field which can have parameters and return values, just as Lua functions. Both parameters and returned values can be typed. This concept allow to express a contract about which parameters suit a function and expected outputs.

Global

When a module is required, it could modify the global environment. To handle those cases, the predefined type global is available. It is a reserved type which will be available everywhere, enabling you to attach field and function to it.
This is a way to express the creation of new global variables when module is loaded.

Type references

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, a function parameter or returned value, they are several kinds 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 defined in 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 defined in 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.

Comments

It is the only source of information of our documentation language. So far, there is no inference from code. So all aspect of the API has to be described explicitly.

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.

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 simplest way to declare a module.

Note: We used #modulename 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.

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 optionally typed with a type reference and have an optional descriptions. Several @return cases are also possible, but LDT inference -which is used for code assistance- only handles the first one. As Lua functions allow to return several values at once, it is possible to define several returned values per @return markup. Returned values can be optionally typed using a type reference.Note: If the first @param is called self, LDT will show completion proposal without this parameter but using : invocation operator.

Short references

It is way to reference a types and their fields in a textual description. You just have to surround a type reference with @{}. You can reference a types and their fields, functions are handled as a specific type of fields.

Reference to types

@{#typename} will refer to type typename defined in current module.

@{modulename} will refer to module named modulename.

@{modulename#typename} will refer to type typename defined in module modulename.

Reference to fields

@{#typename.fieldname} will refer to fieldname which could be a function or field attached to type typename defined in current module.

@{modulename#typename.fieldname} will refer to fieldname which could be a function or field attached to type typename defined in modulename module.

Note: So far, there are no short references for globals.

--------------------------------------------------------------------------------
-- Short description. Long description with a reference to @{io#io.flush}.
--
-- @function [parent=#typename] functionname

Sample of type reference in a description

Ambiguity

It is possible to use dots in type names, but then it becomes hard to differentiate type name from field name. Let's explained the default behavior:

Everything before # is module name

Everything between # and last dot is type name.

Everything after last dot is field name

So in @{module.name#type.name.fieldname} will refer to field fieldname of type named type.name from module module.name.
Well, but what happens when we simply want to reference a type name containing dots? It is possible to surround type name with parenthesis to remove ambiguity.

@{modulenamed#(type.name).fieldname} will refer to field named fieldname from type named type.name defined in module named modulename.

@{modulenamed#(type.name)} will refer to type named type.name from module named modulename

@{#(type.name)} will refer to type named type.name.

Limitations

Markdown

Markdown allows reusable element. As each description is parsed separately, you cannot reuse an element from another description.

Inference

So far, all information about the documented module has to be explicitly described. There is no inference enabling us to extract documentation-valuable information from the code ... yet.

Parsing

We use Metalua to parse comments, and it can't parse only comments. So if you write a documentation only file, ensure it contains a least a valid statement. Most of the time we use, return nil at end of file.

Tips

Usage

When you have a comment block related to a concept, you can give one or several samples of how it should be used by using the @usage keyword.