Module:Docbunto/doc

Docbunto
Description	Is an automatic documentation generator for Scribunto modules.
Author(s)	8nml (Fandom Dev Wiki)
Code source	Docbunto
Status	Alpha
Dependencies	Module:I18n; Module:Lua_lexer; Module:Unindent; Module:Yesno; Module:Arguments;
Using code by	@stevedonovan (GitHub)

This module depends on the following other modules:

Docbunto is an 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.

The following documentation is adapted from wikia:dev:Global Lua Modules/Docbunto.

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 Extension:Scribunto/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(args) (function)

Entrypoint for the module in a format easier for other modules to call.

Parameter: args Module arguments. (table)

Returns: Module documentation output. (string)

docbunto.main(frame) (function)

Entrypoint for the module.

Parameter: frame Module frame. (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.autodoc Whether this is being called automatically to fill in missing 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 938)

'documentation markup for Docbunto not found in $1' (string; line 944)

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.