Template:FunctionPage

From Kolmafia
Revision as of 00:44, 3 March 2010 by imported>StDoodle
Jump to navigation Jump to search


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}}|
function_category=CATEGORY|

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
}}
Retrieved from "https://wiki.kolmafia.us/index.php?title=Template:FunctionPage&oldid=3787"