Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "LDT/User Area/Documentation Language"
(→Global) |
|||
Line 86: | Line 86: | ||
'''Note''': All leading <code>-</code>'s in special comments are trimmed. | '''Note''': All leading <code>-</code>'s in special comments are trimmed. | ||
− | < | + | <source lang="lua"> |
-------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ||
-- Short description. | -- Short description. | ||
-- Long _markdown_ description | -- Long _markdown_ description | ||
− | </ | + | </source> |
<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://en.wikipedia.org/wiki/Markdown Markdown]. | '''Note''': <code>_markdown_</code> is supposed to be interpreted by [http://en.wikipedia.org/wiki/Markdown Markdown]. | ||
− | < | + | <source lang="lua"> |
--- | --- | ||
-- Short description. | -- Short description. | ||
-- Long description | -- Long description | ||
− | </ | + | </source> |
<center><small>Special comment composed of short comments format</small></center> | <center><small>Special comment composed of short comments format</small></center> | ||
− | < | + | <source lang="lua"> |
--[[- | --[[- | ||
Short description. | Short description. | ||
Long description | Long description | ||
]] | ]] | ||
− | </ | + | </source> |
<center><small> Special comment with long comment format</small></center> | <center><small> Special comment with long comment format</small></center> | ||
− | < | + | <source lang="lua">--- Short description. Long description</source> |
<center><small> Special comment in one line</small></center> | <center><small> Special comment in one line</small></center> | ||
Line 116: | Line 116: | ||
A [[Koneki/LDT/Technical_Documentation/Documentation_Language#Type|type]] comment block is a ''special comment'' with a type declaration with <code>@type</code> key word followed by desired type name. | A [[Koneki/LDT/Technical_Documentation/Documentation_Language#Type|type]] comment block is a ''special comment'' with a type declaration with <code>@type</code> key word followed by desired type name. | ||
− | < | + | <source lang="lua"> |
-------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ||
-- Type short description. | -- Type short description. | ||
Line 122: | Line 122: | ||
-- | -- | ||
-- @type typename | -- @type typename | ||
− | </ | + | </source> |
<center><small>Sample of type declaration</small></center> | <center><small>Sample of type declaration</small></center> | ||
Line 129: | Line 129: | ||
Denoted by <code>@module</code> keyword and followed by a module name, a [[Koneki/LDT/Technical_Documentation/Documentation_Language#Module|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. | Denoted by <code>@module</code> keyword and followed by a module name, a [[Koneki/LDT/Technical_Documentation/Documentation_Language#Module|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. | ||
− | < | + | <source lang="lua"> |
-------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ||
-- Module short description. | -- Module short description. | ||
Line 135: | Line 135: | ||
-- | -- | ||
-- @module modulename | -- @module modulename | ||
− | </ | + | </source> |
<center><small>Sample of module declaration.</small></center> | <center><small>Sample of module declaration.</small></center> | ||
When a module is declared, a type with its name is automatically created and returned. So, the following is equivalent to first module sample. | When a module is declared, a type with its name is automatically created and returned. So, the following is equivalent to first module sample. | ||
− | < | + | <source lang="lua"> |
-------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ||
-- Module short description. | -- Module short description. | ||
Line 149: | Line 149: | ||
---@type modulename | ---@type modulename | ||
− | </ | + | </source> |
<center><small>Sample of verbose module declaration</small></center> | <center><small>Sample of verbose module declaration</small></center> | ||
'''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]]. | '''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]]. | ||
Line 155: | Line 155: | ||
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. | ||
− | < | + | <source lang="lua"> |
-------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ||
-- Module short description. | -- Module short description. | ||
Line 162: | Line 162: | ||
-- @module modulename | -- @module modulename | ||
-- @return #string | -- @return #string | ||
− | </ | + | </source> |
<center><small>Sample of module returning custom type</small></center> | <center><small>Sample of module returning custom type</small></center> | ||
'''Note''': We used <code>#string</code> to refer to a [[Koneki/LDT/Technical_Documentation/Documentation_Language#Primitive_references|primitive type]]. | '''Note''': We used <code>#string</code> to refer to a [[Koneki/LDT/Technical_Documentation/Documentation_Language#Primitive_references|primitive type]]. | ||
Line 172: | Line 172: | ||
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. | ||
− | < | + | <source lang="lua"> |
-------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ||
-- Type short description. | -- Type short description. | ||
Line 179: | Line 179: | ||
-- @type typename | -- @type typename | ||
-- @field #string fieldname Field description | -- @field #string fieldname Field description | ||
− | </ | + | </source> |
<center><small>Sample of field declaration in parent type block</small></center> | <center><small>Sample of field declaration in parent type block</small></center> | ||
− | < | + | <source lang="lua"> |
--- | --- | ||
-- Type short description. | -- Type short description. | ||
Line 193: | Line 193: | ||
-- | -- | ||
-- @field [parent=#typename] #string fieldname | -- @field [parent=#typename] #string fieldname | ||
− | </ | + | </source> |
<center><small>Sample of field declaration in dedicated block</small></center> | <center><small>Sample of field declaration in dedicated block</small></center> | ||
Line 201: | Line 201: | ||
'''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. | ||
− | < | + | <source lang="lua"> |
-------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ||
-- Function short description. | -- Function short description. | ||
Line 212: | Line 212: | ||
-- @return #nil, #string Traditional nil and error message | -- @return #nil, #string Traditional nil and error message | ||
-- @return Untyped return description | -- @return Untyped return description | ||
− | </ | + | </source> |
<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>. | '''Note''': It is also possible to document function for types which name contains <code>"."</code>. | ||
− | < | + | <source lang="lua"> |
-------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ||
-- Function short description. | -- Function short description. | ||
Line 223: | Line 223: | ||
-- | -- | ||
-- @function [parent=#typeprefix.typename] functionname | -- @function [parent=#typeprefix.typename] functionname | ||
− | </ | + | </source> |
<center><small>Sample of function declaration related to a type which name contains <code>"."</code></small></center> | <center><small>Sample of function declaration related to a type which name contains <code>"."</code></small></center> | ||
Line 230: | Line 230: | ||
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. | 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. | ||
− | < | + | <source lang="lua"> |
-------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ||
-- Field long description | -- Field long description | ||
Line 241: | Line 241: | ||
-- @function [parent=#global] functionname | -- @function [parent=#global] functionname | ||
-- @param self | -- @param self | ||
− | </ | + | </source> |
<center><small>Sample of global field and function</small></center> | <center><small>Sample of global field and function</small></center> | ||
= Sample mixing code and comments = | = Sample mixing code and comments = | ||
− | < | + | <source lang="lua"> |
--- | --- | ||
-- Module short description. | -- Module short description. | ||
Line 271: | Line 271: | ||
end | end | ||
return M | return M | ||
− | </ | + | </source> |
<center><small>Sample of documented module</small></center> | <center><small>Sample of documented module</small></center> | ||
− | < | + | <source lang="lua"> |
--- A module that allow to manage geometry shapes | --- A module that allow to manage geometry shapes | ||
-- @module geometry | -- @module geometry | ||
Line 313: | Line 313: | ||
return M | return M | ||
− | </ | + | </source> |
<center><small>Sample of documented in-module type</small></center> | <center><small>Sample of documented in-module type</small></center> | ||
Line 329: | Line 329: | ||
'''Note''': So far, there are no short references for ''globals''. | '''Note''': So far, there are no short references for ''globals''. | ||
− | < | + | <source lang="lua"> |
-------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ||
-- Short description. Long description with a reference to @{io#io.flush}. | -- Short description. Long description with a reference to @{io#io.flush}. | ||
-- | -- | ||
-- @function [parent=#typename] functionname | -- @function [parent=#typename] functionname | ||
− | </ | + | </source> |
<center><small>Sample of type reference in a description</small></center> | <center><small>Sample of type reference in a description</small></center> | ||
Line 350: | Line 350: | ||
= Limitations = | = Limitations = | ||
− | |||
− | |||
== Markdown == | == Markdown == | ||
Line 371: | Line 369: | ||
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 <code>@usage</code> keyword. | 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 <code>@usage</code> keyword. | ||
− | < | + | <source lang="lua"> |
-------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ||
-- Module short description. | -- Module short description. | ||
Line 379: | Line 377: | ||
-- @usage local modulename = require 'modulename' | -- @usage local modulename = require 'modulename' | ||
-- @usage require('modulename') | -- @usage require('modulename') | ||
− | </ | + | </source> |
<center><small>Sample of module declaration with usage markup.</small></center> | <center><small>Sample of module declaration with usage markup.</small></center> |
Revision as of 09:32, 20 September 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.
Contents
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.
Special comments are handled only if they describe a concept.
Note: All leading -
's in 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 simplest 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 #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.
-------------------------------------------------------------------------------- -- 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
keyword followed by optional 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.
-------------------------------------------------------------------------------- -- 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 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.
-------------------------------------------------------------------------------- -- Function short description. -- Function long description -- -- @function [parent=#typename] functionname -- @param self Parameter description -- @param #string parametername Parameter description -- @return #number Typed return description -- @return #nil, #string Traditional nil and error message -- @return Untyped return description
Note: It is also possible to document function for types which name contains "."
.
-------------------------------------------------------------------------------- -- Function short description. -- Function long description -- -- @function [parent=#typeprefix.typename] functionname
"."
Global comment block
To declare a function or a field with a type reference as global, you just have to attach it to the global
type.
-------------------------------------------------------------------------------- -- Field long description -- -- @field [parent=#global] #string fieldname -------------------------------------------------------------------------------- -- Function short description. Function long description -- -- @function [parent=#global] functionname -- @param self
Sample mixing code and comments
--- -- Module short description. -- Module _long description_ -- -- @module modulename local M = {} --- -- Field description -- -- @field [parent=#modulename] #string fieldname M.fieldname = 'field value' --- -- Function short description. -- Function long description -- -- @function [parent=#modulename] functionname -- @param self Parameter description -- @return #number Typed return description -- @return #nil, #string Traditional nil and error message function M.functionname(self) return 0 end return M
--- A module that allow to manage geometry shapes -- @module geometry local M = {} --- A rectangle -- @type rectangle -- @field [parent=#rectangle] #number x horizontal position, 0 by default -- @field [parent=#rectangle] #number y vertical position, 0 by default -- @field [parent=#rectangle] #number width, 100 by default -- @field [parent=#rectangle] #number height, 100 by default local R = {x=0, y=0, width=100, height=100, } --- 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 --- 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 return M
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
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.
-------------------------------------------------------------------------------- -- Module short description. -- Module long description -- -- @module modulename -- @usage local modulename = require 'modulename' -- @usage require('modulename')