Difference between revisions of "Template:Doc"
Komidore64 (talk | contribs) (replace instances of <code> with Code template) |
Komidore64 (talk | contribs) |
||
| Line 1: | Line 1: | ||
| − | <includeonly>{{/doc}}</includeonly><noinclude>{{doc/start}} | + | <includeonly>{{/doc}}</includeonly> |
| + | <noinclude>{{doc/start}} | ||
Document how a template works and how to use it. | Document how a template works and how to use it. | ||
== Usage == | == Usage == | ||
| − | Create a subpage of the template called | + | Create a subpage of the template called <code>doc</code>, place a <code><nowiki>{{doc/start}}</nowiki></code> at the start of your documentation, and <code><nowiki>{{doc/end}}</nowiki></code> at the end. |
| − | On the main template page add | + | On the main template page add <code><nowiki><noinclude>{{clear}}{{doc}}</noinclude></nowiki></code> on a newline at the end of the template. |
Documentation subpages will automatically be added to [[:Category:Documentation templates]]. | Documentation subpages will automatically be added to [[:Category:Documentation templates]]. | ||
| Line 14: | Line 15: | ||
=== clear === | === clear === | ||
| − | If your main template page has floating content and you would like to stop it from going over the documentation, put | + | If your main template page has floating content and you would like to stop it from going over the documentation, put <code><nowiki>{{doc/start|clear}}</nowiki></code> instead of <code><nowiki>{{doc/start}}</nowiki></code> on your documentation page. |
| − | This is also useful for templates not using | + | This is also useful for templates not using <code><nowiki><includeonly></nowiki></code> tags, as it will put some space between the template and the documentation box. |
=== nodoc=1 === | === nodoc=1 === | ||
| − | If a template has no documentation and you don't know how to use it, put | + | If a template has no documentation and you don't know how to use it, put <code><nowiki>{{doc/start|nodoc=1}}</nowiki></code> (or if the template needs clear as well, <code><nowiki>{{doc/start|clear|nodoc=1}}</nowiki></code>) instead of <code><nowiki>{{doc/start}}</nowiki></code> on your documentation page. |
The documentation's background will become red to make it more noticeable, and the page will be added to [[:Category:Templates with no documentation]]. | The documentation's background will become red to make it more noticeable, and the page will be added to [[:Category:Templates with no documentation]]. | ||
| Line 26: | Line 27: | ||
=== baddoc=1 === | === baddoc=1 === | ||
| − | Similar to | + | Similar to <code>nodoc</code>, <code>baddoc</code> is used to mark templates that '''do''' have documentation, but it isn't very good. This can mean it doesn't have enough examples, doesn't explain all the functions properly, or doesn't explain the point of the template well. |
The documentation's background will become yellow to make it more noticeable, and the page will be added to [[:Category:Templates with bad documentation]]. | The documentation's background will become yellow to make it more noticeable, and the page will be added to [[:Category:Templates with bad documentation]]. | ||
| − | If both | + | If both <code>nodoc</code> and <code>baddoc</code> are specified, <code>baddoc</code> will be ignored. |
== Example == | == Example == | ||
| − | Let's say we want to add a template named | + | Let's say we want to add a template named <code>HelloWorld</code>. Its contents are the following: |
<pre><nowiki> | <pre><nowiki> | ||
| Line 40: | Line 41: | ||
</nowiki></pre> | </nowiki></pre> | ||
| − | To document how this template works for other editors, we create a subpage of it called | + | To document how this template works for other editors, we create a subpage of it called <code>doc</code>, having the full article name of <code>HelloWorld/doc</code>. |
Within that subpage we'll put the following wikitext: | Within that subpage we'll put the following wikitext: | ||
| Line 53: | Line 54: | ||
Say hello to a name. | Say hello to a name. | ||
| − | {{ | + | {{HelloWorld|NAME}} |
== Example == | == Example == | ||
| − | {{ | + | {{HelloWorld|James}} |
gives: | gives: | ||
| Line 65: | Line 66: | ||
</nowiki></pre> | </nowiki></pre> | ||
| − | Now that we've documented our | + | Now that we've documented our <code>HelloWorld</code> template, we need to reference our documentation from the template by adding it at the bottom. |
<pre><nowiki> | <pre><nowiki> | ||
| Line 73: | Line 74: | ||
Now the template's documentation will be displayed any time the template is viewed! | Now the template's documentation will be displayed any time the template is viewed! | ||
| − | |||
[[Category:Documentation templates]] | [[Category:Documentation templates]] | ||
</noinclude> | </noinclude> | ||
Latest revision as of 17:29, 6 December 2020
Document how a template works and how to use it.
Usage
Create a subpage of the template called doc, place a {{doc/start}} at the start of your documentation, and {{doc/end}} at the end.
On the main template page add <noinclude>{{clear}}{{doc}}</noinclude> on a newline at the end of the template.
Documentation subpages will automatically be added to Category:Documentation templates.
Optional parameters
clear
If your main template page has floating content and you would like to stop it from going over the documentation, put {{doc/start|clear}} instead of {{doc/start}} on your documentation page.
This is also useful for templates not using <includeonly> tags, as it will put some space between the template and the documentation box.
nodoc=1
If a template has no documentation and you don't know how to use it, put {{doc/start|nodoc=1}} (or if the template needs clear as well, {{doc/start|clear|nodoc=1}}) instead of {{doc/start}} on your documentation page.
The documentation's background will become red to make it more noticeable, and the page will be added to Category:Templates with no documentation.
baddoc=1
Similar to nodoc, baddoc is used to mark templates that do have documentation, but it isn't very good. This can mean it doesn't have enough examples, doesn't explain all the functions properly, or doesn't explain the point of the template well.
The documentation's background will become yellow to make it more noticeable, and the page will be added to Category:Templates with bad documentation.
If both nodoc and baddoc are specified, baddoc will be ignored.
Example
Let's say we want to add a template named HelloWorld. Its contents are the following:
Hello, {{{1}}}!
To document how this template works for other editors, we create a subpage of it called doc, having the full article name of HelloWorld/doc.
Within that subpage we'll put the following wikitext:
{{doc/start}}
Say hello!
== Usage ==
Say hello to a name.
{{HelloWorld|NAME}}
== Example ==
{{HelloWorld|James}}
gives:
Hello, James!
{{doc/end}}
Now that we've documented our HelloWorld template, we need to reference our documentation from the template by adding it at the bottom.
Hello, {{{1}}}!
<noinclude>{{clear}}{{doc}}</noinclude>
Now the template's documentation will be displayed any time the template is viewed!
