Template:FunctionPage

From Kolmafia
Revision as of 16:06, 25 February 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.

Editing Function Information

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.

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.

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.

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.

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 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.

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 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.

Miscellaneous

The see_also parameter takes a template, and will parse up to 12 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).

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.

The Function Page Master List

The following is the full function call with all possible parameters. Please note that you would rarely, if ever, require everything shown.

{{FunctionPage|
page_name=FUNCTION_NAME|
function_category=CATEGORY|
function1_return_type=DATATYPE|
function1_returns_also=SECONDARY_DATAYPE_OR_DELETE|
function1_parameter1={{Param|TYPE|SHORTDESC}}|
function1_parameter1_desc=DESCRIPTION_OF_PARAM|
function1_parameter2={{Param|TYPE|SHORTDESC}}|
function1_parameter2_desc=DESCRIPTION_OF_PARAM|
function1_parameter3={{Param|TYPE|SHORTDESC}}|
function1_parameter3_desc=DESCRIPTION_OF_PARAM|
function1_parameter4={{Param|TYPE|SHORTDESC}}|
function1_parameter4_desc=DESCRIPTION_OF_PARAM|
function1_parameter5={{Param|TYPE|SHORTDESC}}|
function1_parameter5_desc=DESCRIPTION_OF_PARAM|
function2_return_type=DATATYPE|
function2_returns_also=SECONDARY_DATAYPE_OR_DELETE|
function2_parameter1={{Param|TYPE|SHORTDESC}}|
function2_parameter1_desc=DESCRIPTION_OF_PARAM|
function2_parameter2={{Param|TYPE|SHORTDESC}}|
function2_parameter2_desc=DESCRIPTION_OF_PARAM|
function2_parameter3={{Param|TYPE|SHORTDESC}}|
function2_parameter3_desc=DESCRIPTION_OF_PARAM|
function2_parameter4={{Param|TYPE|SHORTDESC}}|
function2_parameter4_desc=DESCRIPTION_OF_PARAM|
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|
code1={{CodeSample|
title=CODE EXAMPLE TITLE|
description=DESCRIPTION OF CODE|
code=
<syntaxhighlight lang="c">
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
</syntaxhighlight>}}|
see_also={{SeeAlso|FIRST|SECOND|ETC}}|
cli_equiv=LIST CLI EQUIVALENT|
more_info=A LINE TO NOTIFY OF EXTERNAL INFO|
special=SPECIAL NOTES SUCH AS NOT-LOGGED-IN VALUE
}}

Replace everything in CAPS with appropriate information for the given page.


Retrieved from "https://wiki.kolmafia.us/index.php?title=Template:FunctionPage&oldid=3765"