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:{{BASEPAGENAME}}|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.

An initial summary-line is prefixed by three (3) 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.

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

@field

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

The description is the documentation following the summary. (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.