Module:Sandbox/Jeblad/LuaDoc/doc

Usage

Usual call for documentation of a single module, like a replacement for the usual documentation page, would be like this

{{#invoke:LuaDoc|build|{{FULLPAGENAME}}}}

In the actual code there will be specially formatted comments. All comments acted upon by this uses the single line comment. (Is there any reason why we should use other kinds of comments? They are usefull for commenting out blocks? How to describe local functions?)

Note that all text is processed as wikitext, and it is possible to link internally and externally as seems fit. This also creates some problems as part of the text will have spaces or page breaks in odd places.

An initial summary-line is prefixed by three (3) hyphens (dashes), and double as a marker for the place where the code is to be divided into chunks. The stuff in each chunk is precessed separately. The summary will be marked as such, and it will be possible to use it as a fragment identifier.

A single line comment following a summary line will be added to an empty description. If the line contains text it will be joined with a dividing space, if it is empty it will add a newline. The newline can be further processed and given special markup.

A tag is prefixed by two (2) hyphens (dashes), a single at-sign (@) and a tag name. The following text can be further split and given special markup.

A single line comment following a tag will be joined with the preceeding tag line. If the line contains text it will be joined with a dividing space, if it is empty it will add a newline. The newline can be further processed and given special markup.

Unrecognized tags will be rendered in place with a generic mechanism, but all tags with a leading x- will be rejected.

Available tags

A series of different tags are recognized (it is the intention to support these)

@author <text>

One or more authors of the module. Use one line per author.

@copyright <text>

One or more copyright notices of the module. Copyright is an identification of the entity that is allowed to set the license.

@license <text>

One or more licenses for the module. The license is the document that says why we can use the module.

@provenance <text>

One or more entries for the provenance, that is history of ownership for the module. Link this to the external source if suitable.

@release <text>

Free format string to describe the module or fragments release. Usually this will only be used for imported modules. For internal modules the revision id should be sufficient. It could be that we need a way to track breaking changes.

@since <date|version|revision> <text>

The date, version, or revision when some functionality was added. The text is a free format string to describe the module or fragments functionality.

@deprecated <date|version|revision> <text>

The date, version, or revision is when the deprecation was added. The text is a free format string to describe the module or fragments deprecation state. It is a warning about upcoming removal of the functionality, and the module or fragment should not be used in any new code. The text may identify a future date, version, or revision when the functionality is removed.

@var <word?> <text?>

Describe a variable definition. This imply a variable-class. (Not sure about this one, its like the signature of the function.)

@field <word?> <text?>

Describe a table field definition. This imply a variable-class.

@param <word> <text>

Describe function parameters. It requires the name of the parameter and its description. This imply a function-class.

@return <text>

Describe a return value of the function. Since Lua can return multiple values, this tag could appear more than once. This imply a function-class.

@see <text>

Refers to other descriptions of functions or tables. This spawns a separate list in a navigation box.

@usage <text>

Describe the usage of the function or variable. This is one of several such free sections. The tag will be localized as necessary.

Inferred tags

Some tags will be extracted from the following block of code if missing (it is the intention to support these)

@class <word>

The first documentation block will be assumed to be of class module, and later ones will have classes inferred from the code block unless it is specified explicitly.

@description <text>

The description is the documentation following the summary, but can be set explicitly. (Not sure if this should be described here, and if it should have a tag.)

@name <word>

The name of the function or table definition. This is usually inferred from simple code analysis, and the programmer does not need to define it. (The programmer should not add it at all.)

@access <word>

Whether or not the function or variable is public or private. This will be error prone if inferred from the code.