Help:Template documentation

Documentation of a template or function allows us to quickly identify and understand what it is, why it exists, and how to use it. {{tdoc}} implements a simple, tag-based system, directly based on MediaWiki core's Doxygen usage.

Procedure

To be placed at the start of the template page, outside its transclusion area; either before <onlyinclude> begins, or wrapped in </noinclude> tags:

{{tdoc
 | Concise little blurb addressing the how, why, and where this could and/or should be used.
 | 
 | @example <code>{{template| input }}</code> --> Output
 | @param string $name What input is needed
 | @return string What output is expected.
}}

This will format the tag data into a concise docblock, adding also some automatic tools like cross-usage links and a demo skeleton for easy copy-paste.

If the template page is using <onlyinclude>, please also wrap the inner contents with <includeonly> so the empty code result is hidden.

Format

Tag meanings and values are interpreted and processed in Lua. | arguments effectively mimic * in a Doxygen docblock; blank "lines" can be used for formatting without impacting the output. Except where tag parts have meaning as parameters, all wikitext markup will work.

Non-blank lines past the initial summary must begin with a valid @tag. Some accept their own parameters; These are processed as the respective first "words" (separated by   whitespace boundaries) of the value string. In other words, since @param has (itself) three parameters, <type>, <name> and <description>, the first two words in @param string title Name of the page would be recognized as <type> and <name>, with the full remainder—no matter how many words/spaces— as the <description>.

Parameters

All template parameters are inherently wikitext strings, meaning there aren't really "types" in the classical programming sense. However, we still try to honor this idea by defining in terms of compatibility or interaction between a value and certain logic situations. (They're useful also in establishing common conventions for say, boolean checks, which might have multiple approaches for ultimately the same result.)

Write as	Traditional basis	Our usage/meaning
string	String	The standard type; anything not covered by one of the following descriptions. Explain as specifically as possible the expected format of the text: should it be a link? bulleted list? HTML tag? That knowledge can often be insightful even beyond the parameter itself.
int	Integer	Values compatible with operational functions such as {{#expr:}}/{{#ifexpr:}}) even if not immediately being fed to one. If not being covered already, parameters of this type should be given default {{{param|0}}}; {{#expr:}} for example will throw an error if attempting to operate on an empty null value.
bool	Boolean	Binary "is or isn't", represented by true or false, as relevant to conditional logic. For a variety of transclusion-related reasons, usage of {{#ifeq:}} with this format tends to be more reliable than the traditional {{#if:}} "is null" format. Constructing around positive tests—that is, comparing to true—is usually good practice, though context and convenience will of course influence the most effective option.
array	Array	At this time, we don't have ArrayFunctions or any similar extensions which implement array-like options; if ever you see this type, it will mean something specific to that template and (should) be explained accordingly.

In setting up template parameters, it is encouraged to leverage aliasing in such a way that they can be explicitly or implicitly passed, respectively by name= or numeric position. The latter are not actually trimmed as the former are; safe construction looks like {{{name|{{trim|{{{1|}}}}}}}}, usually in a variable to not have to do that every time. Any such parameter must then be marked with a $ in the documentation.

Tools

For free inputs, there are many formatting templates available and which are often useful:

• {{code}} - Formats a code snippet either in plain text format or with specific links, wrappers, or highlighting. Otherwise it is really shorthand for <code> which can just be used instead.
• {{codeblock}} - <syntaxhighlight> implementation, returning a styled <pre> block.

List of tags

Tags are defined here and each have different formatting, parameters, and so on. Lines beginning with unrecognized @tags are simply discarded and won't impact the output.

Following the below order is recommended, but not required. If you don't have a reason to change them around, stick with the default.

Tag Name	Parameters	Description
@todo	$info	Notes for future work and improvements
@var	$info	After a template ends, any variable it defines will then remain in the global scope of the page. If leveraging, please state the variable's name and meaning, and potentially the "recipient" template if it's specific enough.
@see	$info	Related reading, either immediately relevant, or which lend helpful context. Good for other templates or sections.
@source	$info	Extension or specific MediaWiki version from which a function or item originates.
@ingroup	$info	<noinclude/> category
@param	$type $name $	Parameter types, names, and usage descriptions.
@return	$info	What the end output is expected to be. As it will most likely be a #string, follow the same guidelines for describing, also considering other templates or functions that might want to use it.
@throws	$name $	Name of possible debug messages, and conditions which lead to them. Built-in function errors ({{#expr:}} operation failures, Cargo SQL warnings) should be accommodated and avoided in design of the template, but when depending on user input, replaced with a local message. Remember that the former are defined for their own respective functions, not necessarily their use environment – most will be, to the average user, unhelpful jargon.
@author	$info	If the template is copied from another wiki, give credit to the original author(s); at bare minimum, link to their project where the code was obtained. Locally, if your own work is original and significant (something creative or wholistic) feel free to add your name.

In the free text summary, avoid too much re-treading of info covered by the @tag sections. More importantly, don't use it instead of any tags! Besides just consistency, some of the data might be stored and referenced by other pages.

See also

• Module:Tdoc, logic for tag system
• Help:Comments, broader documentation philosophy