Module:Docbunto/doc

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

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 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 [https://www.lua.org/pil/16.1.html emulated class] variable. A @type tag is rendered as a header for the class name, with the description in a paragraph below.

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 [https://github.com/stevedonovan/LDoc/blob/master/tests/funmod.lua 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 [https://github.com/stevedonovan/LDoc/blob/master/tests/funmod.lua function module].

These are typed versions of subitem tags. These tags are added for backwards compatibility with [https://github.com/stevedonovan/LDoc 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.

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.

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

;@image (single-line; single-use)

:Infobox image for {{t|Infobox Lua}}. Only supports single images.

;@caption (single-line; single-use)

:Infobox image caption for {{t|Infobox Lua}}.

;@release (single-line; single-use)

:Release status for the module, indicating stability. See the {{t|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 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.

These tags are added for backwards compatibility with [https://github.com/keplerproject/luadoc 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.

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.

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

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 #format-ref 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 on MediaWiki.

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

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 or `code`
• Math: $E=mc^2$ or $$E=mc^2$$
• Chemical equations: H2O 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.

|autodoc=1}}

{{Sandbox other||

{{uncategorized}}

}}

Category:Module documentation pages