User:Wlgrin/Sandbox/TDoc/i/Parameter

From Wikimedia Commons, the free media repository
Jump to navigation Jump to search
Documentation[ view · edit · history · purge ]
This documentation is transcluded from User:Wlgrin/Sandbox/TDoc/i/Parameter/doc.

{{TDoc/i/Parameter}} creates a text box intended for documenting a parameter to a template. It is intended for use in template documentation.

This template is part of the {{TDoc}} collection of helper templates.

Purpose[edit]

Intended for the “usage” or “parameters” section of template documentation, {{TDoc/i/Parameter}} produces a text box with fields that can accommodate:

  • the name of the parameter;
  • its description;
  • a list of allowed values;
  • whether the parameter is required (and, if not, its default value or the default behaviour of the template);
  • a list of related parameters;
  • and a few annotated (but not illustrated) examples.

For example:

parameter-name
This is the basic description of the parameter.
More information can be included to cover the details of what the parameter does, how to use it, how not to abuse it, and more.
Optional. Default value: fallback (If no default-value is supplied, the parameter is marked as required.)
Examples
  1. parameter-name=Some value that is meaningful in the <span style="font-weight:bold;">[[en:Context (computing)|context]]</span> at hand.
    The sample code must be in a <syntaxhighlight> (or <nowiki>) element to prevent execution.
  2. parameter-name=Some other interesting case
  3. parameter-name=Yet something else
    Up to 9 examples can be provided.

Parameters[edit]

name, name-first, name-last
name
name-first, name-last
The name of the parameter.

The first form (parameter name) is used to document a simple parameter. The second form, using two parameters (name-first and name-last) is used to document together a numbered series of parameters (for example: author1, author2, etc.). Both forms are mutually exclusive (if either name-first or name-last is not blank, both are used and any value passed to name is ignored).

For numbered (unnamed) parameters (such as {{{1}}}), simply use their number (with parameter name to document each separately, or with name-first and name-last if they are used to pass several values of the same type).

To document related parameters (like, here, name, name-first and name-last), simply use parameter name with a line break (<br/>) in the value. However, introducing a line break (or any markup) in the name will produce a corrupted entry in the table of contents. In that case, override the TOC entry with parameter toc-entry.

Required.
See also
toc-entry
Examples
  1. |name=birth-date
  2. |name=1
    Here, we are documenting the use of parameter {{{1}}}.
  3. |name-first=author1 |name-last=author5
    This will produce a title in the form “author1 … author5”.
description-text
description-text
A short description of the parameter.
It should be a one- or two-line summary description. It may be followed by a longer description, passed in parameter description-subtext.
Required.
See also
description-subtext
Example
|description-text=Date of birth in the Gregorian calendar, YYYY-MM-DD format.
description-subtext
description-subtext
A detailed description of the parameter, if necessary.

It should cover all non-obvious aspects of using the parameter: format of the value, how it will be used, etc. Generally, it will not contain allowed values (normally described using parameters allowed1-value … allowed9-value) or examples (normally described using parameters example1-code … example9-code).

To separate the text into blocks and paragraphs, use normal <br/> and <p> … </p> elements.

Optional. Default value: blank (No description sub-text.)
See also
description-text
Example
|description-subtext=If the date of birth is disputed, enter “ca.” (''circa''), followed by a date (or year), a list of dates (separated with commas) or a range (two dates or years separated with an n-dash).
allowed-intro
allowed-intro
An introduction to the sub-section of allowed values.
This parameter can be used either to introduce the list of allowed values or to replace it entirely. For example, when several parameters share the same list of allowed values, it may be preferable to present the list with the most used of those parameters and to refer to it in the documentation of the others.
Optional. Default value: blank (No introduction to the list of allowed values.)
See also
allowed1-value … allowed9-value
Example
|allowed-intro=See allowed values for parameter <tt>display-mode</tt>.
allowed1-value … allowed9-value
allowed1-value … allowed9-value
A value (or a range of values) that may be assigned to the parameter.

Up to 9 values (or ranges/subsets of values) can be described. Each value may have a description (supplied with parameters allowed1-description … allowed9-description).

This section is only useful for parameters that admit a finite set of values (such as a boolean parameter, or a parameter used to request one of several supported modes of operation). A single range of valid values (for example, a percentage admitting a value in the range [20…50]) is best described using parameter description_subtext. If several ranges produce different behaviours, on the other hand, each range may be described using an allowedn-value parameter. For parameters whose range of values is fairly obvious (for example, a parameter taking a month full name in the range [January … December]), it would often be superfluous to enter the full list.

If several parameters share the same list of allowed values, it may be preferable to present the list only once and refer to it elsewhere using parameter allowed-intro.

Allowed values
%‌%%NIL%%%Special value “%%%NIL%%%” will display the word none, signifying that the parameter was not supplied.
%‌%%BLANK%%%Special value “%%%BLANK%%%” will display the word blank, signifying that the parameter has a blank value. The same result is obtained by passing a blank value to parameter default-value.
%‌%%OTHER%%%Special value “%%%OTHER%%%” will display the words “all other values”, representing all values other than those already listed. It should naturally appear last in the list of allowed values.
%‌%%SPECIAL%%%/custom descriptionSpecial value “%%%SPECIAL%%%” followed by a / and the text of your choice will display your text in the style used for special values, signifying that it is a description of a value and not a value that should be typed verbatim.
all other valuesAny value other than the special values listed above will be displayed verbatim, indicating that the parameter contains that text.
Optional. Default value: blank (No list of allowed values.)
See also
allowed-intro, allowed1-description … allowed9-description
Example
|allowed1-value=collapsed |allowed2-value=uncollapsed |allowed3-value=never
allowed1-description … allowed9-description
allowed1-description … allowed9-description
A description for one of the allowed values (or ranges of values).
It is used to provide non-obvious information about an allowed value (listed using one of the parameters allowed1-value … allowed9-value).
Optional. Default value: blank (No list of allowed values.)
See also
allowed1-value … allowed9-value
Example
|allowed1-description=Will cause the contents of the table to be hidden by default and a show/hide toggle button to be displayed on the first row. |allowed2-description=Will cause the contents of the table to be shown by default and a show/hide toggle button to be displayed on the first row. |allowed3-description=Will make the table non-collapsible: the contents of the table are always shown and no show/hide toggle button is displayed.
default-value
default-value
The default value assigned to an optional parameter.

If the parameter is optional, its default value must be listed here. If you pass a blank value (or special value “%%%BLANK%%%”), the word blank will be displayed. If no default value is specified, the parameter is automatically marked as required. Note that a blank value for this parameter is not the same as its absence.

A description of the default value can be supplied using parameter default-description. If allowed values are enumerated (using parameters allowed1-value … allowed9-value), the default value should naturally be one of them.

Allowed values
See allowed values for parameters allowed1-value … allowed9-value.
Optional. Default value: none (No default value; the parameter is marked as required.)
See also
default-description
Examples
  1. |description-value=
    A blank value will display: blank
  2. |
    The absence of a default-value (and default-description) will cause the parameter to be marked required.
default-description
default-description
The description of the default value or of the behaviour it produces.
If a default value is listed (using default-value) but its effect is not obvious, a description can be supplied here. However, if allowed values are enumerated (using parameters allowed1-value … allowed9-value), the default value, along with its full description, should appear in that list and the description should not be reproduced here.
Optional. Default value: blank (No description for the default value, if any.)
See also
default-value
Example
|default-description=No title inserted
see-also
see-also
A list of related parameters.
Parameter names in the list should be enclosed in a <tt> element and separated with commas. To specify a numbered series of parameters, use the first and last names in the series, separated with an ellipsis itself surrounded with spaces.
Optional. Default value: blank (No “see also” sub-section.)
Example
|see-also=<tt>authors</tt>, <tt>author1 … author5</tt>
example1-code … example9-code
example1-code … example9-code
An example illustrating how to pass a value through the parameter.

Such examples are rarely necessary but may be useful with thorny notation or in providing sample code that can be copied by the reader. A description, supplied through one of parameters example1-description … example9-description, can be used to further clarify non-obvious aspects.

Because this value is a snippet of code that could contain wiki markup (styling, links, references to other templates, etc.), it must be enclosed in an element that disables execution, such as <nowiki> or <syntaxhighlight>. The latter is preferred not only because it can highlight HTML tags but also because, unlike <nowiki>, it also preserves HTML character entities (such as &amp;). Because of current limitations in MediaWiki, the template cannot automatically apply <nowiki> or <syntaxhighlight> to argument values. To use syntax highlighting, enclose your code like this:

<syntaxhighlight lang="html5" enclose="none">your sample code</syntaxhighlight>

The sample above may be copied for re-use. By contrast, do not copy/paste other examples (like those below), because the <syntaxhighlight>…</syntaxhighlight> tags contain invisible characters to prevent them from being interpreted within the documentation page.

If you use <nowiki>, you should also set the corresponding parameter of family example1-format … example9-format to value “pre-formatted” so that proper styling is applied. If you use <syntaxhighlight>, you may omit the format parameter as its default value is syntax-highlighting.

Optional. Default value: blank (No examples.)
See also
example1-format … example9-format, example1-description … example9-description
Examples
  1. |example1-code=<‌syntaxhighlight lang="html5" enclose="none">|title=Du côté de chez Swann<‌/syntaxhighlight>
  2. |example1-code=<‌syntaxhighlight lang="html5" enclose="none">
    |author1=Arthur Stanley Jefferson
    |author2=Norvell Hardy
    <‌/syntaxhighlight>
    This example illustrates how more than one parameter can be shown in an example. This is particularly useful when documenting a numbered series of parameters. Within an example, each parameter assignment is, by convention, prefixed with a vertical bar | precisely to allow showing multiple parameters.
  3. |example1-code=<‌syntaxhighlight lang="html5" enclose="none">
    |first=Julius
    |last=Henry
    <‌/syntaxhighlight>
    |example1-description=<tt>first</tt> and <tt>last</tt> names will be displayed together as “Julius Henry”.
    More rarely, one may want to show in a single example different (but related) parameters working together like, here, parameters for first and last names. Illustrating how several parameters work together often requires more complex examples that are best placed in the “examples” section of the documentation page (rather than the “examples” sub-section of parameter descriptions).
  4. |example1-code=<nowiki>title=Du côté de chez Swann</nowiki>
    |example1-format=pre-formatted
    This example shows the use of <nowiki> instead of syntax highlighting; using <nowiki> requires also specifying the “pre-formatted” format.
example1-format … example9-format
example1-format … example9-format
The format in which the code of an example is supplied.
To avoid execution, the code of examples (produced with parameters example1-code … example9-code) must be contained in a <nowiki> or, preferably, a <syntaxhighlight> element. To ensure that the correct styling is applied, you must specify which element was used through the corresponding examplen-format parameter.
Allowed values
pre-formattedThe code is contained in a <nowiki> element. White space and line endings must be preserved. Additional line breaks may be inserted, if lines are too long.
syntax-highlightingThe code is contained in a <syntaxhighlight> element, which will take care of styling: white space and line endings will be preserved; additional line breaks may be inserted, if lines are too long.
noneThe code supplies its own styling; no additional styling should be applied.
Optional. Default value: syntax-highlighting (Using syntax highlighting gives the best results. And, if you use it, you do not need to use the format parameter, since its default value is adequate.)
See also
example1-code … example9-code, example1-description … example9-description
example1-description … example9-description
example1-description … example9-description
The description for an example of code using the parameter.
Each example produced with one of parameters example1-code … example9-code can have a description explaining the example’s salient points.
Optional. Default value: blank (No example description.)
See also
example1-code … example9-code
toc-entry
toc-entry
Whether to add a TOC entry and the name to use for it.

For each parameter, an entry is generated in the page’s table of contents, as well as an anchor that can be used to link directly to the parameter's documentation (for example, [[User:Wlgrin/Sandbox/TDoc/i/Parameter#name, name-first, name-last]]). This feature can be disabled by passing special value “%%%NIL%%%” to parameter toc-entry.

The name of the parameter (as passed to parameter name or parameters name-first and name-last) is reused to produce the text of the TOC entry for the parameter. If the name contains any markup (for example, a line break), the resulting TOC entry will be corrupted. In that case, parameter toc-entry should be set to a purely textual version of the name (i.e., without any markup): it will be automatically used in the TOC entry instead of the name.

Though rare, the use of a line break <br/> in a name may be useful to document several overlapping parameters. For example, see (on this page) parameter name, whose documentation also covers parameters name-first and name-last.

Allowed values
%‌%%NIL%%%Disables the generation of a TOC entry for this parameter.
blankEnables the generation of a TOC entry for this parameter, using the value specified through parameters name or name-first and name-last.
all other valuesEnables the generation of a TOC entry for this parameter, using the value specified through parameter toc-entry.
Optional. Default value: blank (Generates a TOC entry using the parameter’s name.)
See also
name
Examples
  1. |toc-entry=%%%NIL%%%
    No TOC entry will be produced for this parameter.
  2. |name=name<br/> name-first, name-last |toc-entry=name, name-first, name-last
    Overriding the name value in the TOC entry when the name contains markup, as done on this documentation page for parameter name.

Examples[edit]

Please note that the code samples in this section have been slightly altered to prevent execution of the <syntaxhighlight> elements on this documentation page. If you copy and paste any of those code samples, please re-type all <syntaxhighlight> and </syntaxhighlight> tags within them (you can safely copy the tags shown in this paragraph).

Documenting a set of allowed values[edit]

collapse
Whether the table is collapsible and initially collapsed.
If JavaScript is not enabled on the user’s client browser, this parameter will have no effect and the table will not be made collapsible.
Allowed values
collapsedWill cause the contents of the table to be hidden by default and a show/hide toggle button to be displayed on the first row.
uncollapsedWill cause the contents of the table to be shown by default and a show/hide toggle button to be displayed on the first row.
neverWill make the table non-collapsible: the contents of the table are always shown and no show/hide toggle button is displayed.
Optional. Default value: collapsed
See also
layout-mode
Example
|collapse=collapsed

See also[edit]

Retrieved from "https://commons.wikimedia.org/w/index.php?title=User:Wlgrin/Sandbox/TDoc/i/Parameter&oldid=63511309"