Template:FunctionPage: Difference between revisions

From Kolmafia
Jump to navigation Jump to search
imported>StDoodle
mNo edit summary
imported>StDoodle
m fix title 2.0
 
(50 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<noinclude><p>This is template for a function page (for just a function line, see "Template:Function").</p>
<includeonly>{{TOCright}}{{DISPLAYTITLE:{{{name}}}()}}{{#if: {{{needscode|}}}|{{CodeRequest}}}}{{#if: {{{improvecode|}}}|{{CodeRequest|better=yes}}}}<h2>Function Syntax</h2>{{#if: {{{function1|}}}|{{{function1}}}}}{{#if: {{{function2|}}}|{{{function2}}}}}{{#if: {{{function3|}}}|{{{function3}}}}}{{#if: {{{function4|}}}|{{{function4}}}}}{{#if: {{{function5|}}}|{{{function5}}}}}
{{#if: {{{function_description|}}}|<p> {{{function_description}}} </p>}}{{#if: {{{code1|}}}|{{{code1}}}}}{{#if: {{{code2|}}}|{{{code2}}}}}{{#if: {{{code3|}}}|{{{code3}}}}}{{#if: {{{code4|}}}|{{{code4}}}}}{{#if: {{{code5|}}}|{{{code5}}}}}{{#if: {{{cli_equiv|}}}|<h2>CLI Equivalent</h2><p>{{{cli_equiv}}}</p>}}{{#if: {{{see_also|}}}|{{{see_also|}}}}}{{#if: {{{more_info|}}}|<h2>More Information</h2><p>{{{more_info}}}</p>}}{{#if: {{{special|}}}|<h2>Special</h2><p>{{{special}}}</p>}}
[[Category:Ash Functions]]
</includeonly>
<noinclude>
{| align="right"
  | __TOC__
  |}
<p>This is template for a function page (for just a function line, see "[[Template:Function]]").</p>
<h2>General Notes</h2>
<h2>General Notes</h2>
<p>Any parameter line that is not used on a page should be deleted entirely. Do not leave a line with nothing after the equals sign, or with the CAPS helpful information.</p>
<p>Any parameter line that is not used on a page should be deleted entirely. Do not leave a line with nothing after the equals sign, or with the CAPS helpful information.</p>
<p>Make sure all pipes -- <nowiki>|</nowiki> -- are used properly. They must always exist between each parameter in a template call.</p>
<p>Make sure all pipes -&gt; <nowiki>|</nowiki> &lt;- are used properly. They must always exist between each parameter in a template call.</p>
<p>There should not be a space between a parameter value and the pipe; doing so sometimes causes formatting problems.</p>
<p>There should not be a space between a parameter value and the pipe; doing so sometimes causes formatting problems.</p>
<p>For all numbered duplicates (functions, parameters, code), make sure they are used in order. Don't delete code1, and then use code3 and code5, for example.</p>
<p>For all numbered duplicates (functions, parameters, code), make sure they are used in order. Don't delete code1, and then use code3 and code5, for example.</p>
<h2>Setting Defaults</h2>
<p>"name," "aggregate," "return_type" and "return_also" are all set via a special template for defining variables. This allows them to be re-used in following function calls, without having to be re-typed.</p>
*"name" is set to the function's name, without any parenthesis (which are all added as appropriate by the templates).
*"aggregate" is set to any string if the default return value of the function is an [[Aggregate]] (map). Delete this line if this is not the case. This can be overridden on a function-call by function-call basis, so if most versions of the function return an aggregate, it would help to set this variable. (But in that case, make sure to delete the line for "aggregate=" in each function call that doesn't return an aggregate.)
*"return_type" is set to the default datatype returned by the function. If a "simple" datatype, such as string, int, $item, etc., enter only that word. If the function returns an aggregate, use the whole aggregate definition.
*"return_also" is used for functions that return multiple data types. For example, some functions can return both [[string]] and [[buffer]]. In such a case, set "return_type" to one of them, and "return_also" to the other.
<h2>Editing Function Information</h2>
<h2>Editing Function Information</h2>
<p>The function page accepts up to 5 different versions of the function itself. Each must have the same name, but the parameters can differ. Each function accepts up to 5 parameters. You can also use up to 5 code samples on each page.</p>
<p>The function page accepts up to 5 different versions of the function itself. Each needs to be assigned to a parameter with names of "parameter1" through "parameter5." Use them in numerical order; don't skip around.</p>
<p>To edit each function version, change the return_type to match one of the valid data types. If two data types can be returned by the function (as is the case with several functions that can return both a string and a buffer), enter that for the functions returns_also value. If there is no secondary return type, delete the line for returns_also.</p>
<p>To edit each function version, edit all parameters for the call to [[Template:FunctionPage]] as needed.</p>
<p>For each function parameter, a sub-template is called. The first value to pass is the data type for the parameter. The second is a short description of the parameter that follows the data type on the function syntax line. Delete all entries for parameters that are not used.</p>
*In most cases, "name," "aggregate," "return_type" and "return_also" should be the same as the defaults for the page, and these lines can be left with their calls to "#var" as they are. This even applies to "aggregate" and "return_also" when you don't want to use said parameters; if the defaults have been omitted above, you can leave these lines in the individual function calls or delete them as desired.
<p>Following the parameter is a desc for the parameter. All desc lines present will display directly below their function call. In the case of functions that can be called multiple ways, where the parameters of the shortest call are included in the longer calls, it is recommended that you use desc on the last function only. If the parameters are different between different function calls, by all means use desc for each function. An example desc for a parameter of "int count" might be "Where ''count'' is the number of items to purchase." Please make sure to use 2 single-quotes around the parameter short description for consistency in formatting.</p>
*"parameter1" through "parameter5" are set to the functions parameters via a call to [[Template:Param]]. Use each in order, and don't skip around. For more info, see the template page.
*"p1desc" through "p2desc" are shown as a list below the function call line. See [[Template:Function]] for more info on their use. Note that in most cases of multiple function calls, some parameters are optional, but each usually builds on the next, reusing previous parameters. If this is the case, it's recommended that you only provide descriptions in the last function call and be sure to note when one is optional.
<p>After all of the information for the (maximum 5) function calls is the parameter function_description. This is used for the overall description of the function's purpose. Generally, it should say what is returned.</p>
<p>After all of the information for the (maximum 5) function calls is the parameter function_description. This is used for the overall description of the function's purpose. Generally, it should say what is returned.</p>
<p>Specifying the data type is redundant, as it is already given on the function call line. A good example for function_description are "Returns the name of the logged-in character, all in lowercase." Try to avoid "Returns the name of the logged-in character as a string." </p>
<p>Specifying the data type for "function_description" is redundant, as it is already given on the function call line. A good example for function_description is "Returns the name of the logged-in character, all in lowercase." Try to avoid "Returns the name of the logged-in character as a string." </p>
<p>If multiple paragraphs are warranted for function_description, place paragraph end & start tags between them (ie "<nowiki>End of first paragraph.</p><p></nowiki>Start of second..."). Don't use markup at the beginning and end of the description; the template adds it automatically.</p>
<p>If multiple paragraphs are warranted for function_description, place paragraph end & start tags between them (ie "<nowiki>End of first paragraph.</p><p></nowiki>Start of second..."). Don't use markup at the beginning and end of the description; the template adds it automatically. Similarly, you can place lists & links inside the function_description using wiki standard markup.</p>
<h2>Code Samples</h2>
<h2>Code Samples</h2>
<p>Each code sample (assigned to parameters code1 through code5) can include a title, description, and the code itself.</p>
<p>Each code sample (assigned to parameters code1 through code5) can include a title, description, and the code itself.</p>
<p>The title will be displayed as a class-2 heading. In most cases, using the title for the first sample only will suffice (in which case it should be set to "Code Sample" or "Code Samples").</p>
<p>The title will be displayed as a class-2 heading. In most cases, using the title for the first sample only will suffice (in which case it should be set to "Code Sample" or "Code Samples").</p>
<p>Normally, you will want a description for each code sample. As with function_description, if you need to have multiple paragraphs, add html markup between them (but not at the start and end).</p>
<p>Normally, you will want a description for each code sample. As with function_description, if you need to have multiple paragraphs, add html markup between them (but not at the start and end).</p>
<p>The code parameter is very picky. Do NOT try to edit any part of this parameter other than typing the code where you see "CODE GOES HERE". Remember to use spaces for indenting (I'm trying to standardize on two spaces per indent on this wiki). Note that nothing inside the actual code area will expand as wiki text; don't use html tags, wiki markup, etc.; they won't be parsed.</p>
<p>The code parameter is very picky. Do NOT try to edit any part of this parameter other than typing the code where you see "CODE GOES HERE". Remember to use spaces for indenting (I'm trying to standardize on three spaces per indent on this wiki). Note that nothing inside the actual code area will expand as wiki text; don't use html tags, wiki markup, etc.; they won't be parsed.</p>
<h2>Multiple Functions & Code Samples</h2>
<p>For clarity, each function & code assignment should have a blank line between them. These will be ignored when the page is parsed.</p>
<p>To have an additional function call or code sample, simple copy and paste the entire block, increment the number on the assignment (ie change "function1=..." to "function2=...") and make and modifications required.</p>
<h2>Miscellaneous</h2>
<h2>Miscellaneous</h2>
<p>The see_also parameter takes a template, and will parse up to 12 functions as links in a special <nowiki><div></nowiki>.  Note that the functions should be passed by their wiki page name (the SeeAlso template will add parentheses).</p>
<p>The see_also parameter takes a template, and will parse up to 16 functions as links in a special <nowiki><div></nowiki>.  Note that the functions should be passed by their wiki page name (the SeeAlso template will add parentheses). For more info, see [[Template:SeeAlso]].</p>
<p>The cli_equiv parameter is for noting a CLI equivalent to the function. Set this to the line of text (or lines, with inner tags as mentioned prevsiously) to describe the command. Wiki and html markup may be used (for example, to link to a page with more information).</p>
<p>The cli_equiv parameter is for noting a CLI equivalent to the function. Set this to the line of text (or lines, with inner tags as mentioned prevsiously) to describe the command. Wiki and html markup may be used (for example, to link to a page with more information).</p>
<p>The more_info parameter is used to describe and link to an external page (usually, a thread on the kolmafia.us forums) with more information on using the function. In general, this parameter should be avoided, and all applicable information should be included on the page. As with cli_equiv, this parameter can be a single or multiple lines, with html and wiki markup as needed.</p>
<p>The more_info parameter is used to describe and link to an external page (usually, a thread on the kolmafia.us forums) with more information on using the function. In general, this parameter should be avoided, and all applicable information should be included on the page. As with cli_equiv, this parameter can be a single or multiple lines, with html and wiki markup as needed.</p>
<p>The special parameter is used for any footnote information to add about the function. Useful for adding a line regarding the default return value for non-logged-in characters for functions where such information would differ, for example.</p>
<p>The special parameter is used for any footnote information to add about the function. Useful for adding a line regarding the default return value for non-logged-in characters for functions where such information would differ, for example.</p>
<p>The following is the full function call with all possible parameters. Please note that you would rarely, if ever, require everything shown.</p>
<h2>Sample Call to Function Page</h2>
<p>The following is the basic call to this template. Note that the assignment under "function1" & under "code1" can each be repeated up to 5 times, total. Don't forget to delete unnecessary lines!</p>
<pre>
<pre>
{{FunctionPage|
{{
page_name=FUNCTION_NAME|
#vardefine:name|FUNCTION_NAME}}{{
function_category=CATEGORY|
#vardefine:return_type|DATATYPE}}{{
function1_return_type=DATATYPE|
#vardefine:aggregate|ANYTHING_IF_AGG_OR_DELETE}}{{
function1_returns_also=SECONDARY_DATAYPE_OR_DELETE|
#vardefine:return_also|SECONDARY_DATATYPE_OR_DELETE}}{{
function1_parameter1={{Param|TYPE|SHORTDESC}}|
 
function1_parameter1_desc=DESCRIPTION_OF_PARAM|
FunctionPage|
function1_parameter2={{Param|TYPE|SHORTDESC}}|
 
function1_parameter2_desc=DESCRIPTION_OF_PARAM|
name={{#var:name}}|
function1_parameter3={{Param|TYPE|SHORTDESC}}|
 
function1_parameter3_desc=DESCRIPTION_OF_PARAM|
function1={{Function|
function1_parameter4={{Param|TYPE|SHORTDESC}}|
name={{#var:name}}|
function1_parameter4_desc=DESCRIPTION_OF_PARAM|
aggregate={{#var:aggregate}}|
function1_parameter5={{Param|TYPE|SHORTDESC}}|
return_type={{#var:return_type}}|
function1_parameter5_desc=DESCRIPTION_OF_PARAM|
return_also={{#var:return_also}}|
function2_return_type=DATATYPE|
parameter1={{Param|DATATYPE|SHORT_DESC}}|
function2_returns_also=SECONDARY_DATAYPE_OR_DELETE|
parameter2={{Param|DATATYPE|SHORT_DESC}}|
function2_parameter1={{Param|TYPE|SHORTDESC}}|
parameter3={{Param|DATATYPE|SHORT_DESC}}|
function2_parameter1_desc=DESCRIPTION_OF_PARAM|
parameter4={{Param|DATATYPE|SHORT_DESC}}|
function2_parameter2={{Param|TYPE|SHORTDESC}}|
parameter5={{Param|DATATYPE|SHORT_DESC}}|
function2_parameter2_desc=DESCRIPTION_OF_PARAM|
p1desc=LONG_DESCRIPTION_OF_PARAMETER|
function2_parameter3={{Param|TYPE|SHORTDESC}}|
p2desc=LONG_DESCRIPTION_OF_PARAMETER|
function2_parameter3_desc=DESCRIPTION_OF_PARAM|
p3desc=LONG_DESCRIPTION_OF_PARAMETER|
function2_parameter4={{Param|TYPE|SHORTDESC}}|
p4desc=LONG_DESCRIPTION_OF_PARAMETER|
function2_parameter4_desc=DESCRIPTION_OF_PARAM|
p5desc=LONG_DESCRIPTION_OF_PARAMETER
function2_parameter5={{Param|TYPE|SHORTDESC}}|
}}|
function2_parameter5_desc=DESCRIPTION_OF_PARAM|
 
function3_return_type=DATATYPE|
function3_returns_also=SECONDARY_DATAYPE_OR_DELETE|
function3_parameter1={{Param|TYPE|SHORTDESC}}|
function3_parameter1_desc=DESCRIPTION_OF_PARAM|
function3_parameter2={{Param|TYPE|SHORTDESC}}|
function3_parameter2_desc=DESCRIPTION_OF_PARAM|
function3_parameter3={{Param|TYPE|SHORTDESC}}|
function3_parameter3_desc=DESCRIPTION_OF_PARAM|
function3_parameter4={{Param|TYPE|SHORTDESC}}|
function3_parameter4_desc=DESCRIPTION_OF_PARAM|
function3_parameter5={{Param|TYPE|SHORTDESC}}|
function3_parameter5_desc=DESCRIPTION_OF_PARAM|
function4_return_type=DATATYPE|
function4_returns_also=SECONDARY_DATAYPE_OR_DELETE|
function4_parameter1={{Param|TYPE|SHORTDESC}}|
function4_parameter1_desc=DESCRIPTION_OF_PARAM|
function4_parameter2={{Param|TYPE|SHORTDESC}}|
function4_parameter2_desc=DESCRIPTION_OF_PARAM|
function4_parameter3={{Param|TYPE|SHORTDESC}}|
function4_parameter3_desc=DESCRIPTION_OF_PARAM|
function4_parameter4={{Param|TYPE|SHORTDESC}}|
function4_parameter4_desc=DESCRIPTION_OF_PARAM|
function4_parameter5={{Param|TYPE|SHORTDESC}}|
function4_parameter5_desc=DESCRIPTION_OF_PARAM|
function5_return_type=DATATYPE|
function5_returns_also=SECONDARY_DATAYPE_OR_DELETE|
function5_parameter1={{Param|TYPE|SHORTDESC}}|
function5_parameter1_desc=DESCRIPTION_OF_PARAM|
function5_parameter2={{Param|TYPE|SHORTDESC}}|
function5_parameter2_desc=DESCRIPTION_OF_PARAM|
function5_parameter3={{Param|TYPE|SHORTDESC}}|
function5_parameter3_desc=DESCRIPTION_OF_PARAM|
function5_parameter4={{Param|TYPE|SHORTDESC}}|
function5_parameter4_desc=DESCRIPTION_OF_PARAM|
function5_parameter5={{Param|TYPE|SHORTDESC}}|
function5_parameter5_desc=DESCRIPTION_OF_PARAM|
function_description=DESCRIPTION_OF_FUNCTION|
function_description=DESCRIPTION_OF_FUNCTION|
code1={{CodeSample|
code1={{CodeSample|
title=CODE EXAMPLE TITLE|
title=CODE EXAMPLE TITLE|
description=DESCRIPTION OF CODE|
description=DESCRIPTION OF CODE|
code=
code=
<syntaxhighlight lang="c">
<syntaxhighlight>
CODE GOES HERE
</syntaxhighlight>}}|
code2={{CodeSample|
title=CODE EXAMPLE TITLE|
description=DESCRIPTION OF CODE|
code=
<syntaxhighlight lang="c">
CODE GOES HERE
</syntaxhighlight>}}|
code3={{CodeSample|
title=CODE EXAMPLE TITLE|
description=DESCRIPTION OF CODE|
code=
<syntaxhighlight lang="c">
CODE GOES HERE
</syntaxhighlight>}}|
code4={{CodeSample|
title=CODE EXAMPLE TITLE|
description=DESCRIPTION OF CODE|
code=
<syntaxhighlight lang="c">
CODE GOES HERE
</syntaxhighlight>}}|
code5={{CodeSample|
title=CODE EXAMPLE TITLE|
description=DESCRIPTION OF CODE|
code=
<syntaxhighlight lang="c">
CODE GOES HERE
CODE GOES HERE
</syntaxhighlight>}}|
</syntaxhighlight>
}}|
 
see_also={{SeeAlso|FIRST|SECOND|ETC}}|
see_also={{SeeAlso|FIRST|SECOND|ETC}}|
cli_equiv=LIST CLI EQUIVALENT|
cli_equiv=LIST_CLI_EQUIVALENT_INFO|
more_info=A LINE TO NOTIFY OF EXTERNAL INFO|
more_info=A_LINE_TO_NOTIFY_OF_EXTERNAL_INFO|
special=SPECIAL NOTES SUCH AS NOT-LOGGED-IN VALUE
special=SPECIAL_NOTES_SUCH_AS_NOT-LOGGED-IN_VALUE
}}
}}
</pre>
</pre>
<p>Replace everything in CAPS with appropriate information for the given page.</p>
[[Category:Basic Templates]]
[[Category:Basic Templates]]
</noinclude>
</noinclude>
<includeonly>
{| align="right"
  | __TOC__
  |}{{#customtitle:{{{page_name}}}()|{{{page_name}}}()}}<h2>Function Syntax</h2>{{#if: {{{function1_return_type|}}}|<p>{{Function|function_name={{{page_name}}}|returns={{{function1_return_type}}}|returns2={{{function1_returns_also|}}}|parameter1={{{function1_parameter1|}}}|parameter2={{{function1_parameter2|}}}|parameter3={{{function1_parameter3|}}}|parameter4={{{function1_parameter4|}}}|parameter5={{{function1_parameter5|}}}}}</p>}}{{#if: {{{function1_parameter1_desc|}}}|{{{function1_parameter1_desc}}}<br />}}{{#if: {{{function1_parameter2_desc|}}}|{{{function1_parameter2_desc}}}<br />}}{{#if: {{{function1_parameter3_desc|}}}|{{{function1_parameter3_desc}}}<br />}}{{#if: {{{function1_parameter4_desc|}}}|{{{function1_parameter4_desc}}}<br />}}{{#if: {{{function1_parameter5_desc|}}}|{{{function1_parameter5_desc}}}<br />}}{{#if: {{{function2_return_type|}}}|<p>{{Function|function_name={{{page_name}}}|returns={{{function2_return_type}}}|returns2={{{function2_returns_also|}}}|parameter1={{{function2_parameter1|}}}|parameter2={{{function2_parameter2|}}}|parameter3={{{function2_parameter3|}}}|parameter4={{{function2_parameter4|}}}|parameter5={{{function2_parameter5|}}}}}</p>}}{{#if: {{{function2_parameter1_desc|}}}|{{{function2_parameter1_desc}}}<br />}}{{#if: {{{function2_parameter2_desc|}}}|{{{function2_parameter2_desc}}}<br />}}{{#if: {{{function2_parameter3_desc|}}}|{{{function2_parameter3_desc}}}<br />}}{{#if: {{{function2_parameter4_desc|}}}|{{{function2_parameter4_desc}}}<br />}}{{#if: {{{function2_parameter5_desc|}}}|{{{function2_parameter5_desc}}}<br />}}{{#if: {{{function3_return_type|}}}|<p>{{Function|function_name={{{page_name}}}|returns={{{function3_return_type}}}|returns2={{{function3_returns_also|}}}|parameter1={{{function3_parameter1|}}}|parameter2={{{function3_parameter2|}}}|parameter3={{{function3_parameter3|}}}|parameter4={{{function3_parameter4|}}}|parameter5={{{function3_parameter5|}}}}}</p>}}{{#if: {{{function3_parameter1_desc|}}}|{{{function3_parameter1_desc}}}<br />}}{{#if: {{{function3_parameter2_desc|}}}|{{{function3_parameter2_desc}}}<br />}}{{#if: {{{function3_parameter3_desc|}}}|{{{function3_parameter3_desc}}}<br />}}{{#if: {{{function3_parameter4_desc|}}}|{{{function3_parameter4_desc}}}<br />}}{{#if: {{{function3_parameter5_desc|}}}|{{{function3_parameter5_desc}}}<br />}}{{#if: {{{function4_return_type|}}}|<p>{{Function|function_name={{{page_name}}}|returns={{{function4_return_type}}}|returns2={{{function4_returns_also|}}}|parameter1={{{function4_parameter1|}}}|parameter2={{{function4_parameter2|}}}|parameter3={{{function4_parameter3|}}}|parameter4={{{function4_parameter4|}}}|parameter5={{{function4_parameter5|}}}}}</p>}}{{#if: {{{function4_parameter1_desc|}}}|{{{function4_parameter1_desc}}}<br />}}{{#if: {{{function4_parameter2_desc|}}}|{{{function4_parameter2_desc}}}<br />}}{{#if: {{{function4_parameter3_desc|}}}|{{{function4_parameter3_desc}}}<br />}}{{#if: {{{function4_parameter4_desc|}}}|{{{function4_parameter4_desc}}}<br />}}{{#if: {{{function4_parameter5_desc|}}}|{{{function4_parameter5_desc}}}<br />}}{{#if: {{{function5_return_type|}}}|<p>{{Function|function_name={{{page_name}}}|returns={{{function5_return_type}}}|returns2={{{function5_returns_also|}}}|parameter1={{{function5_parameter1|}}}|parameter2={{{function5_parameter2|}}}|parameter3={{{function5_parameter3|}}}|parameter4={{{function5_parameter4|}}}|parameter5={{{function5_parameter5|}}}}}</p>}}{{#if: {{{function5_parameter1_desc|}}}|{{{function5_parameter1_desc}}}<br />}}{{#if: {{{function5_parameter2_desc|}}}|{{{function5_parameter2_desc}}}<br />}}{{#if: {{{function5_parameter3_desc|}}}|{{{function5_parameter3_desc}}}<br />}}{{#if: {{{function5_parameter4_desc|}}}|{{{function5_parameter4_desc}}}<br />}}{{#if: {{{function5_parameter5_desc|}}}|{{{function5_parameter5_desc}}}<br />}}
{{#if: {{{function_description|}}}|<p>{{{function_description}}}</p>}}
{{#if: {{{code1|}}}|{{{code1}}}}}{{#if: {{{code2|}}}|{{{code2}}}}}{{#if: {{{code3|}}}|{{{code3}}}}}{{#if: {{{code5|}}}|{{{code4}}}}}{{#if: {{{code5|}}}|{{{code5}}}}}{{#if: {{{cli_equiv|}}}|<h2>CLI Equivalent</h2><p>{{{cli_equiv}}}</p>}}{{#if: {{{see_also|}}}|{{{see_also|}}}}}{{#if: {{{more_info|}}}|<h2>More Information</h2><p>{{{more_info}}}</p>}}{{#if: {{{special|}}}|<h2>Special</h2><p>{{{special}}}</p>}}
[[Category:Ash Functions]]
{{#if: {{{function_category|}}}|[[Category:{{{function_category}}}]]}}
</includeonly>

Latest revision as of 17:55, 21 June 2010


This is template for a function page (for just a function line, see "Template:Function").

General Notes

Any parameter line that is not used on a page should be deleted entirely. Do not leave a line with nothing after the equals sign, or with the CAPS helpful information.

Make sure all pipes -> | <- are used properly. They must always exist between each parameter in a template call.

There should not be a space between a parameter value and the pipe; doing so sometimes causes formatting problems.

For all numbered duplicates (functions, parameters, code), make sure they are used in order. Don't delete code1, and then use code3 and code5, for example.

Setting Defaults

"name," "aggregate," "return_type" and "return_also" are all set via a special template for defining variables. This allows them to be re-used in following function calls, without having to be re-typed.

  • "name" is set to the function's name, without any parenthesis (which are all added as appropriate by the templates).
  • "aggregate" is set to any string if the default return value of the function is an Aggregate (map). Delete this line if this is not the case. This can be overridden on a function-call by function-call basis, so if most versions of the function return an aggregate, it would help to set this variable. (But in that case, make sure to delete the line for "aggregate=" in each function call that doesn't return an aggregate.)
  • "return_type" is set to the default datatype returned by the function. If a "simple" datatype, such as string, int, $item, etc., enter only that word. If the function returns an aggregate, use the whole aggregate definition.
  • "return_also" is used for functions that return multiple data types. For example, some functions can return both string and buffer. In such a case, set "return_type" to one of them, and "return_also" to the other.

Editing Function Information

The function page accepts up to 5 different versions of the function itself. Each needs to be assigned to a parameter with names of "parameter1" through "parameter5." Use them in numerical order; don't skip around.

To edit each function version, edit all parameters for the call to Template:FunctionPage as needed.

  • In most cases, "name," "aggregate," "return_type" and "return_also" should be the same as the defaults for the page, and these lines can be left with their calls to "#var" as they are. This even applies to "aggregate" and "return_also" when you don't want to use said parameters; if the defaults have been omitted above, you can leave these lines in the individual function calls or delete them as desired.
  • "parameter1" through "parameter5" are set to the functions parameters via a call to Template:Param. Use each in order, and don't skip around. For more info, see the template page.
  • "p1desc" through "p2desc" are shown as a list below the function call line. See Template:Function for more info on their use. Note that in most cases of multiple function calls, some parameters are optional, but each usually builds on the next, reusing previous parameters. If this is the case, it's recommended that you only provide descriptions in the last function call and be sure to note when one is optional.

After all of the information for the (maximum 5) function calls is the parameter function_description. This is used for the overall description of the function's purpose. Generally, it should say what is returned.

Specifying the data type for "function_description" is redundant, as it is already given on the function call line. A good example for function_description is "Returns the name of the logged-in character, all in lowercase." Try to avoid "Returns the name of the logged-in character as a string."

If multiple paragraphs are warranted for function_description, place paragraph end & start tags between them (ie "End of first paragraph.</p><p>Start of second..."). Don't use markup at the beginning and end of the description; the template adds it automatically. Similarly, you can place lists & links inside the function_description using wiki standard markup.

Code Samples

Each code sample (assigned to parameters code1 through code5) can include a title, description, and the code itself.

The title will be displayed as a class-2 heading. In most cases, using the title for the first sample only will suffice (in which case it should be set to "Code Sample" or "Code Samples").

Normally, you will want a description for each code sample. As with function_description, if you need to have multiple paragraphs, add html markup between them (but not at the start and end).

The code parameter is very picky. Do NOT try to edit any part of this parameter other than typing the code where you see "CODE GOES HERE". Remember to use spaces for indenting (I'm trying to standardize on three spaces per indent on this wiki). Note that nothing inside the actual code area will expand as wiki text; don't use html tags, wiki markup, etc.; they won't be parsed.

Multiple Functions & Code Samples

For clarity, each function & code assignment should have a blank line between them. These will be ignored when the page is parsed.

To have an additional function call or code sample, simple copy and paste the entire block, increment the number on the assignment (ie change "function1=..." to "function2=...") and make and modifications required.

Miscellaneous

The see_also parameter takes a template, and will parse up to 16 functions as links in a special <div>. Note that the functions should be passed by their wiki page name (the SeeAlso template will add parentheses). For more info, see Template:SeeAlso.

The cli_equiv parameter is for noting a CLI equivalent to the function. Set this to the line of text (or lines, with inner tags as mentioned prevsiously) to describe the command. Wiki and html markup may be used (for example, to link to a page with more information).

The more_info parameter is used to describe and link to an external page (usually, a thread on the kolmafia.us forums) with more information on using the function. In general, this parameter should be avoided, and all applicable information should be included on the page. As with cli_equiv, this parameter can be a single or multiple lines, with html and wiki markup as needed.

The special parameter is used for any footnote information to add about the function. Useful for adding a line regarding the default return value for non-logged-in characters for functions where such information would differ, for example.

Sample Call to Function Page

The following is the basic call to this template. Note that the assignment under "function1" & under "code1" can each be repeated up to 5 times, total. Don't forget to delete unnecessary lines!

{{
#vardefine:name|FUNCTION_NAME}}{{
#vardefine:return_type|DATATYPE}}{{
#vardefine:aggregate|ANYTHING_IF_AGG_OR_DELETE}}{{
#vardefine:return_also|SECONDARY_DATATYPE_OR_DELETE}}{{

FunctionPage|

name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|DATATYPE|SHORT_DESC}}|
parameter2={{Param|DATATYPE|SHORT_DESC}}|
parameter3={{Param|DATATYPE|SHORT_DESC}}|
parameter4={{Param|DATATYPE|SHORT_DESC}}|
parameter5={{Param|DATATYPE|SHORT_DESC}}|
p1desc=LONG_DESCRIPTION_OF_PARAMETER|
p2desc=LONG_DESCRIPTION_OF_PARAMETER|
p3desc=LONG_DESCRIPTION_OF_PARAMETER|
p4desc=LONG_DESCRIPTION_OF_PARAMETER|
p5desc=LONG_DESCRIPTION_OF_PARAMETER
}}|

function_description=DESCRIPTION_OF_FUNCTION|

code1={{CodeSample|
title=CODE EXAMPLE TITLE|
description=DESCRIPTION OF CODE|
code=
<syntaxhighlight>
CODE GOES HERE
</syntaxhighlight>
}}|

see_also={{SeeAlso|FIRST|SECOND|ETC}}|
cli_equiv=LIST_CLI_EQUIVALENT_INFO|
more_info=A_LINE_TO_NOTIFY_OF_EXTERNAL_INFO|
special=SPECIAL_NOTES_SUCH_AS_NOT-LOGGED-IN_VALUE
}}