Module:Documentation/Documentation

From Zelda Wiki, the Zelda encyclopedia
Jump to: navigation, search

This is the documentation page for Module:Documentation

This module is used to generate documentation for modules (e.g. Module:UtilsMarkup) and module-based templates (e.g. Template:Letter). The documentation is generated from a specification in the form of a Lua table. This specification can be re-used to parse and validate input, as well as generate TemplateData. It can also be used to generate usage examples. For module functions, one can can specify what the expected output should be for a given example, turning it into an automated unit test.

The advantages of this design are as follows:

  • Documentation is standardized.
  • The documentation for a module/template is located on the same page as the module code, allowing for both to be edited together at the same time.
  • Template documentation is less likely to be incorrect or out of date. For example, there is no chance that the documentation says a parameter is optional when in fact it is required—the code that documents which parameters are required is the same code used to actually verify that required args are present when the template is used.

For documenting simple templates that are not module-based, see Template:Usage and Template:Examples.

This module exports the following functions.

Templates

To generate documentation for a module-based documentation, add this to the template page:

<noinclude>{{#invoke:Documentation|Template}}</noinclude>

And add this to the module page:

<module code>

p.Templates = {
 ["Template Name"] = <TemplateSpec>
}

return p
[TemplateSpec]
purpose
Purpose of the template.
[wip]
Flag to indicate the template is a work in progress.
[storesData]
For /Store templates, use this field to indicate which Data page this template is used on. If present, the template is added to Category:Cargo Storage Templates.
[usesData]
For templates that use Cargo data, use this field to indicate which page(s) the data is stored on. If present, the template is added to Category:Cargo Query Templates.
[usesModuleData]
Set to true for templates that rely on /Data pages in the Module namespace.
format
Indicates how the template should be laid out in source. inline for single-line templates, block for multiline templates.
params

Map of the template parameters. Numerical keys indicate positional parameters. String keys indicate named parameters. A special key named ... indicates a variadic parameter (i.e. a template with a variable number of trailing arguments, such as Template:List).

This data can be used by Module:UtilsArg to parse template arguments.

[name]
Use this to assign names to positional parameters.
[placeholder]
Placeholder to use for argument value when demonstrating template usage. Defaults to <name> for positional parameters; empty string for named parameters.
[type]
One of the Extension:TemplateData types.
[required]
Indicates a required parameter.
[deprecated]
Indicates a parameter that should no longer be used.
[enum]
An array of allowed values. Optionally, a reference key can be added to the Lua table which links to a page listing all the allowed values (see Module:Franchise#enum for example).
[enumDependsOn]
If the allowed values for this parameter depends on the value of another parameter, specify that parameter name here. Then, instead of enum being an array, it can be a function that returns an array. The value of the dependency argument is passed to the function. See Module:Letter for an example.
[default]
Default value for the parameter.
desc
Wikitext description of the parameter.
[canOmit]
Omit parameter from generated boilerplate. Use for parameters that cover edge cases and should thefore not be used in normal circumstances. See Template:Game Rating for example.
[inline]
If true, then the parameter will be printed on the same line as the previous parameter, even if format is set to "block". See Template:Sequence/Store for example.
[trim]
Indicator to utilsArg.parse that this template argument should be trimmed using utilsString.trim.
[nilIfEmpty]
Indicator to utilsArg.parse that this template argument should be made nil if it is an empty string, using utilsString.nilIfEmpty.
[split]
Indicator to utilsArg.parse. If set to true, the template argument is treated as a list of commma-separated values, to be turned into an array using utilsString.split. If set to a string, that string will be used as the splitting pattern.
[sortAndRemoveDuplicates]
Indicator to utilsArg.parse that can be used together with split and enum. If true, then the split array will be sorted according to the order of items in enum. Duplicates and invalid values are be removed.
[repeatedGroup]
This is used to make templates that accept "arrays of objects" or "rows" of input. For an example, see Template:Trading Quest. (Ideally, Template:Tab2 could be using this as well.)
name
The key that the resulting array will be assigned to in the returned argument table.
params
An array of parameter keys (similar to paramOrder), indicating which parameters are repeated.
count

Roughly the maximum amount of times one can expect the params to be repeated. This is merely to decide how many repetitions to include in the boilerplate. It is always possible to repeat more times than this number.

For example, Template:Trading Quest is set to 20. The longest trading quest in the series is 14 items, so 20 is likely to cover any future trading quests.

[paramOrder]
Array of parameter keys indicating what order they should be presented in.
[indent=0]
Number of spaces to indent block-format parameters.
[boilerplate]
Directives for how generate boilerplate for the template.
[before]
Any wikitext entered here will be prepended to the boilerplate
[after]
Any wikitext entered here will be appended to the boilerplate
[list]
If true, boilerplate includes Template:List. See Template:Game Rating for example.
[examples]
Array of argument tables representing different invocations of the template + an optional vertical key. It is possible to add descriptions to specific examples as well. See Template:List for examples.
[vertical=false]
If false, examples are laid out in a single table (e.g. Template:List). If true, examples are listed one after the other (e.g. Template:Letter).

Examples

Modules

Usage

To create module documentation, create the page Module:Module Name/Documentation with the following contents

{{#invoke:Documentation|Module}}

Then on the actual module page, at the end of the script just before the final return, add a Documentation field to the export table.

<module code>

p.Documentation = { <Documentation> }

return p
[Documentation]
functionssections
Map of function names to function documentation. Functions are printed in the order in which they appear in the source code.
[desc]
Description of the function. Use only when clarification is needed—usually the param/returns/cases doc speaks for itself.
params
An array of parameter names. Integrates with Module:Schema.
[_params]
To be specified for functions with an alternative higher-order function.
[returns]
A string describing the return value of the function, or an array of such strings if the function returns multiple values
[cases]
A collection of use cases that double as test cases, plus a couple flags.
[resultOnly]
When true, displays only rendered wikitext as opposed to raw function output. Useful for functions returning strings of complex wikitext.
[outputOnly]
When true, displays only the raw output of the function (opposite of resultOnly). Enabled by default for functions returning data of type other than string.
argssnippet
[desc]
A description of the use case.
[args]
An array of arguments to pass to the function.
[expect]
The expected return value, which is deep-compared against the actual value to determine pass/fail status. Or, an array of such items if there are multiple return values.
[desc]
A description of the use case.
snippet
See Module:UtilsTable for examples of usage.
[expect]
The expected return value, which is deep-compared against the actual value to determine pass/fail status. Or, an array of such items if there are multiple return values.
[wip]
Tags the function doc with Template:UC.

Tests

The expect property transforms documentation examples into actual test cases, using a deep equality assertion between the expected output and actual output. If the assertion fails, the page is added to Category:Modules with failing tests.

This module therefore rolls documentation and testing into one. This approach was chosen over ScribuntoUnit and Docbunto for the following reasons:

  • Module functionality that is worth testing is worth documenting too, and vice-versa. The specification should be written only once, in one place.
  • For modules like Module:UtilsLayout that render a ton of markup, it is not practical to test with coded assertions. In these cases it suffices for module developers to manually check that the examples are outputting correct visuals.
  • A module's code, tests, and documentation are tightly coupled. It's important that they all be on the same page so that they can be edited simultaneously.

Schemas

Main article: Module:Schema

This module integrates with Module:Schema to generate type documentation for function parameters. Note for example the parameter documentation for Module:UtilsLayout#tabs:

data
label
[tooltip]
[defaultTab=1]

The above indicates that:

  • data is expected to be a table with two keys: label and tooltip.
  • label is required and of type string.
  • tooltip is optional and of type string.
  • defaultTab is an optional number whose default value is 1.

Hovering over the key name indicates its expected data type. Types may be marked with symbols:

Type symbol Meaning
string! Required
[string] Optional
{string} Array
<string,record> Map with string keys and record values
string|{string} Either a string or an array of strings
vararg{string} Indicates that a function receives a variable number of arguments

A given schema can have alternative structures. These are indicated with tabs.

Data

Category:Module Data can be documented and validated by adding the following:

Module:ModuleName Module:ModuleName/Data/Documentation
function p.Data()
  return "Should return a representation of the data" 
end

p.Schemas = {
  Data = { <Schema> } -- See [[Module:Schema]]
}
{{#invoke:Documentation|Module}}
{{#invoke:Schema|Validate}}

Examples