Global Lua Modules/Docbunto

**Docbunto** automatic documentation generator for Scribunto modules. The module is based on LuaDoc and LDoc. It produces documentation in the form of MediaWiki markup, using `@tag`-prefixed comments embedded in the source code of a Scribunto module. The taglet parser & doclet renderer Docbunto uses are also publicly exposed to other modules.

Docbunto code items are introduced by a block comment (`--[[]]--`), an inline comment with three hyphens (`---`), or an inline `@tag` comment. The module can use static code analysis to infer variable names, item privacy (`local` keyword), tables (`{}` constructor) and functions (`function` keyword). MediaWiki and Markdown formatting is supported.

Items are usually rendered in the order they are defined, if they are public items, or emulated classes extending the Lua primitives. There are many customisation options available to change Docbunto behaviour.

This module is self-documenting! See §Documentation.

## Lua安裝

### 模組：​

請在您的wiki上建立[[Module:**指令碼錯誤：沒有「common」這個模組。**]]並加入以下代碼：

### 模板:

請在您的wiki上建立[[Template:**指令碼錯誤：沒有「common」這個模組。**]]並加入以下代碼：

## Example

````
--- Item summary.
-- The item description follows. Information provided by the item comment
-- can be formatted with both '''MediaWiki''' and \*\*Markdown\*\* syntax.
-- The comments can generally span multiple lines.
--
-- By leaving empty comment lines, a new paragraph can be made in the
-- documentation. This can be used to give longer explanations whitespace.
--
-- @script ldoc
-- @param {table} options Configuration options.
-- @param {string} options.file Target file.
-- @param[opt] {string} options.filter Output filter.
-- @param[opt] {boolean} options.dump Text output to console.
-- @return {string} Compiled documentation.

````
gives:

`ldoc(options)`
Item summary. The item description follows. Information provided by the item comment can be formatted with both **MediaWiki** and **Markdown** syntax. The comments can generally span multiple lines.
By leaving empty comment lines, a new paragraph can be made in the documentation. This can be used to give longer explanations whitespace.
**Parameters:**
`options` Configuration options. (table)
`options.file` Target file. (string)
`options.filter` Output filter. (string; optional)
`options.dump` Text output to console. (boolean; optional)
**Returns:** Compiled documentation. (string)

## Tags

Docbunto provides fifty two tags to document items. To document subitem types, Docbunto uses JSDoc-style `{type}` prefixes for typed subitem tags (e.g: `@param {bool}` or `@field {string}`. To designate optional subitems, Docbunto uses the LDoc-style `[opt]` modifier affixed to the tag (e.g: `@param[opt] verbose`).

### Item type tags

Item type tags are the heart of Docbunto, and provide the name and type of a documentation item. Each item is rendered as a definition list with a description below it. Subitem tags can be placed alongside the item comments to provide further information.

`@function` (item; specialised; alias `@lfunction`)
Module-level function, either inside a table or outside. The documented, top-level parameters of the function are rendered adjacent to the name in parentheses. Relevant tags include `@param`, `@error`, `@return` and `@factory`.
`@table` (item; specialised)
Module-level table, ideally a table constructor delimited by `{}`. Relevant tags include `@field`.
`@member` (item; generic; alias `@property`)
Module or class data member, typically a primitive value (`string`, `boolean` or `number` type). As this tag denotes a generic type, Docbunto will try to qualify the type with a `{type}` prefix.
`@variable` (item; generic)
Local variable. Can be rendered with a primitive type qualifier, as with `@member`. Implies `@local` tag.
`@section` (section)
Section header, used to structure documentation. The summary (or value) of a `@section` item is rendered as a header, while the description is rendered below it as a paragraph if present.
`@type` (section; class; alias `@typedef`)
Module-level emulated class variable. A `@type` tag is rendered as a header for the class name, with the description in a paragraph below.
### Subitem tags

Subitem tags can be used at the module and item level to associate information with a Lua module or item. These tags are rendered as subitems below the description, inside nested definition or unordered lists.

`@usage` (preformatted multi-line; alias `@code`)
Code demonstration, rendered in preformatted text. The tag provides brace-delimited wikitext or Lua syntax highlighting, depending on the value.
`@param` (multi-line; alias `@argument`)
Parameter tag, accepting multi-line values and `{type}` notation. Optional parameters have `[opt]` affixed to the tag. In module-level comment blocks, this tag implies a function module.
`@field` (multi-line)
Table field name, identified by index key. Supports `{type}` notation for field value.
`@error` (multi-line; alias `@raise`, `@throws` or `@exception`)
Error thrown by a Lua function. Accepts type via `{type}` notation. The line number can be specified by `[number]` affixed to the tag.
`@return` (multi-line; alias `@returns`)
Return value for function, supporting Lua's multiple returns. Accepts type via `{type}` notation, and accepts `[opt]` affixed to the tag if they are not always returned. In module-level comment blocks, this tag implies a function module.
### Typed subitem tags

These are typed versions of subitem tags. These tags are added for backwards compatibility with LDoc. These tags either imply a tag type, or permit types with `type` prefix notation (as with LDoc).

`@tfield` (multi-line)
Typed `@field` tag. Expects `type` prefix without spaces.
`@tparam` (multi-line)
Typed `@param` tag. Expects `type` prefix without spaces.
`@treturn` (multi-line)
Typed `@return` tag. Expects `type` prefix without spaces.
`@bool` (multi-line)
Boolean table field, or boolean function parameter. Implies `boolean` type.
`@func` (multi-line)
Function table field, or subroutine function parameter. Implies `function` type.
`@int` (multi-line)
Integer table field, or integer function parameter. Implies `number` type.
`@number` (multi-line)
Numeric table field, or numeric function parameter. Implies `number` type.
`@string` (multi-line)
String table field, or string function parameter. Implies `string` type.
`@tab` (multi-line)
Tabular table field, or table function parameter. Implies `table` type.
### Module type tags

These tags are used at the project level to identify the module name and type. These tags are usually optional & are used to customise the package name for a module function.

`@module` (executable; invocable; alias `@package`)
Executable Scribunto modules. Docbunto documentation defaults to this type.
`@script` (executable)
Executable scripts (libraries) exclusively used in other modules.
`@classmod` (executable)
Defines a class module used to create objects. Unlike the `@type` tag, class modules are externally usable by other Lua modules.
`@submodule` (non-executable)
Lua code items to be coalesced into another module package.
`@example` (non-executable)
Non-executable code example, used to support documentation.
`@file` (non-executable)
Non-executable, generic Lua modules for consumption by other modules. Often data used by `mw.loadData`.
`@topic` (non-executable)
Static documentation file, designed for human reading. Implies the file is non-executable.
### Module information tags

These tags provide general information about a module, independent of the code items the module contains.

`@image` (single-line; single-use)
Infobox image for {{Infobox Lua}}. Only supports single images.
`@caption` (single-line; single-use)
Infobox image caption for {{Infobox Lua}}.
`@release` (single-line; single-use)
Release status for the module, indicating stability. See the {{Status}} template for accepted values.
`@author` (single-line)
An author for a Lua file, responsible for code development or maintenance.
`@copyright` (single-line; single-use)
Copyright (corporate or crowdsourced) ownership for file. This item is not rendered.
`@license` (single-line; single-use)
License for the source code of the module. This item is not rendered, as it is assumed the code is licensed under CC-BY-SA 3.0 or to the public domain. However, it is a useful substitute to license boilerplate.
`@require` (single-line; alias `@requires`)
Dependency for the module. Accepts the full page name as a value.
`@credit` (single-line; alias `@credits`)
An author of external source code, whose work has been reused in the module.
`@attribution` (single-line)
A contributor who has contributed to a module without authoring it or any source code.
### Flags

Flags are item tags that provide additional information about a Docbunto item. These do not require a value and act as item modifiers.

`@local` (item flag)
Lack of external access or usage for Lua items, outside of their block scope.
`@export` (inline flag)
Precedes export table constructors in factory functions or modules. Docbunto can infer that export field variables are package or class items, and render them as namepaths in the corresponding namespace. If you are mapping a field variable to a different key name, use the `@alias` tag.
`@private` (item flag)
Access restriction flag for Lua items. Alias for the `@private` tag.
`@constructor` (item flag)
Class subroutine used for object creation.
`@static` (item flag)
Whether a class method is independent of class instantiation. In Lua, static methods are called with `Class.method(...)` instead of `Class:method(...)`. When a factory exports functions without a `self`, Docbunto uses this flag to format static methods exported by a class correctly.
### Override tags

These tags are added for backwards compatibility with LuaDoc. They overwrite item information deduced by Docbunto. It is generally advised to avoid using these tags.

`@class` (single-line; identifier)
Type override for Docbunto item, kept for backward compatibility with LuaDoc. Not to be mistaken with the `@type` tag for classes.
`@name` (single-line; identifier)
Variable name override for Docbunto item. The value of the tag is equivalent to the full internal Lua variable name within the module source, and must include any table indexes.
`@alias` (single-line; identifier)
External name for Docbunto item when used by other modules. When an item is exported by a module or factory function, the alias is the external index (including the `[]` square bracket operators).
`@summary` (single-line; alias `@abstract`, `@about` or `@bug`)
Brief item summary for documentation, limited to a sentence.
`@description` (multi-line; alias `@details` or `@discussion`)
Extended item description for documentation. Can span multiple lines and paragraphs.
### Annotation tags

These tags provide comments & explanation for functionality, or issues adjacent to a code item. Annotations can be used globally, in a module or item comment block. However, annotations cannot be used inline in a code item.

`@warning` (multi-line)
Developer warning for users of missing or changing functionality.
`@fixme` (multi-line; alias `@bug`)
Developer bug reminder, to be patched in future.
`@note` (multi-line)
Developer notes for users or other maintainers.
`@todo` (multi-line)
TODO note for developer and other maintainers.
`@see` (multi-line)
Additional, external pages or information to direct the user to.
### Other tags

`@pragma` (single-line)
Processing directive for Docbunto. Allows the developer to override Docbunto options from the source code.
Accepts `[yesno]` modifier affixed to tag; this can be used to deactivate options.
**Usage:**
* `@pragma all` - documents private parameters (like `options.all` set to `true`)
* `@pragma[off] code` - renders article infobox and lede (like `options.code` set to `false`/`nil`)

`@factory` (single-line)
Factory function used for object creation. The value of this tag is the class name for the exported instance. Docbunto prefixes exported items with the class name for convenience. For class methods that are missing a `self` parameter, the `@static` flag can be used.
## Types and item references

Docbunto recognises fourteen **types** and links them to entries in the Lua reference manual. Other types are assumed to be custom classes defined with the `@type` tag in the documentation page. The `noluaref` option will disable these manual links if they become excessive.

Lua whitelisted native types.

* `nil`
* `boolean` (alias `bool`)
* `string`
* `number` (alias `int`)
* `table` (alias `tab`)
* `function` (alias `func`)

Scribunto library classes.

* `DataWrapper` (alias `mw.loadData`)
* `Frame`
* `Lang` (alias `mw.language`)
* `Uri` (alias `mw.uri`)
* `HTMLBuilder` (alias `mw.html`)
* `Msg` (alias `mw.msg`)

**Item references**, in the `@{item|text}` syntax, also support global functions and library items available to Scribunto. These will link to the relevant entry in the standard library documentation or Scribunto library documentation at Fandom.

## Infobox customisation

A custom infobox can be generated by creating **Module:Docbunto/infobox** with a function:

````
--- Infobox for Lua modules.
-- @script infobox
-- @param {table} data Taglet documentation data.
-- @param {string} codepage Code page name.
-- @param {table} frame Template invocation frame.
-- @param {table} options Docbunto configuration options.
-- @return {table} Infobox template data for `frame:expandTemplate`.
return function(data, codepage, frame, options)
    local infobox = {}

    -- Infobox template name.
    infobox.title = 'Infobox Lua'

    -- Infobox argument list.
    infobox.args = {}
    infobox.args.Title = codepage

    return infobox
end

````
## Formatting

Docbunto uses a strict subset of Markdown and MediaWiki syntax. Note that Markdown cannot be used in the documentation preface (`options.preface`).

* Bold: `'''Bold'''` or `**Bold**`
* Italic: `''Emphasis''` or `*Emphasis*`
* Headers: `=== Header ===` or `### Header ###`
These need to be preceded by two newlines to work.
````
-- This line belongs to a module documentation lede.
--
-- ## Usage ##
-- This line belongs to the @{Usage} section.

````
* Definition lists: `; Definition term.` or `: Definition description.`
* Ordered lists: `# Numbered list item`
* Unordered lists: `* Unsorted list item`
* Links: `[https://mediawiki.org MediaWiki]`, `[[mw:MediaWiki]]` or `[https://commonmark.org](Markdown)`
* Item references: `@{item}` or `@{item|text}`
* Code: `<code>code</code>` or ``code``
* Math: `<math display="inline">E=mc^2</math>` or `$$E=mc^2$$`
* Chemical equations: `<chem>H2O</chem>` or `$$\ce{H2O}$$`
* Tables: `{| ... |}` (syntax is described in the tables help page)

Limitations:

* Code blocks are not supported - this simplifies parsing of text paragraphs. The `@usage` tag is available for documenting code examples.
* Markdown tables and open headers (using dashes below the header text) are too complex to parse without a full Markdown parser, and will not be added.

## Documentation

### Package items

`docbunto.main(f)` (function)
Template entrypoint for Template:Docbunto.
**Parameter**: `f` Scribunto frame object. (table)
**Returns**: Module documentation output. (string)
`docbunto.build(modname, options)` (function)
Scribunto documentation generator entrypoint.
**Parameters**:
* `modname` Module page name (without namespace). Default: second-level subpage. (string; optional)
* `options` Configuration options. (table; optional)
	+ `options.all` Include local items in documentation. (boolean; optional)
	+ `options.boilerplate` Removal of boilerplate (license block comments). (boolean; optional)
	+ `options.caption` Infobox image caption. (string; optional)
	+ `options.code` Only document Docbunto code items - exclude article infobox and lede from rendered documentation. Permits article to be edited in VisualEditor. (boolean; optional)
	+ `options.colon` Format tags with a `:` suffix and without the `@` prefix. This bypasses the "doctag soup" some authors complain of. (boolean; optional)
	+ `options.image` Infobox image. (string; optional)
	+ `options.noluaref` Don't link to the Lua reference manual for types. (boolean; optional)
	+ `options.plain` Disable Markdown formatting in documentation. (boolean; optional)
	+ `options.preface` Preface text to insert between lede & item documentation, used to provide usage and code examples. (string; optional)
	+ `options.simple` Limit documentation to descriptions only. Removes documentation of subitem tags such as `@param` and `@field` (see list). (boolean; optional)
	+ `options.sort` Sort documentation items in alphabetical order. (boolean; optional)
	+ `options.strip` Remove table index in documentation. (boolean; optional)
	+ `options.ulist` Indent subitems as `<ul>` lists (LDoc/JSDoc behaviour). (boolean; optional)

`docbunto.taglet(modname, options)` (function)
Docbunto taglet parser for Scribunto modules.
**Parameters**:
* `modname` Module page name (without namespace). (string; optional)
* `options` Configuration options. (table; optional)

**Errors**:
* 'Lua source code not found in $1' (string; line 906)
* 'documentation markup for Docbunto not found in $1' (string; line 912)

**Returns**: Module documentation data. (table)
`docbunto.doclet(data, options)` (function)
Doclet renderer for Docbunto taglet data.
**Parameters**:
* `data` Taglet documentation data. (table)
* `options` Configuration options. (table; optional)

**Returns**: Wikitext documentation output. (string)
`docbunto.tags` (table)
Token dictionary for Docbunto tags. Maps Docbunto tag names to tag tokens.
* Multi-line tags use the `'M'` token.
* Multi-line preformatted tags use the `'ML'` token.
* Identifier tags use the `'ID'` token.
* Single-line tags use the `'S'` token.
* Flags use the `'N'` token.
* Type tags use the `'T'` token.