Template:Nasal doc: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
(Undo revision 103040 by Red Leader (talk))
 
(35 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<includeonly>=={{{name|function}}}==
<includeonly>{{#ifeq: {{{mode|}}} | class | | {{#if: {{{private|}}} | :<span style="color: grey"><tt>'''{{{private}}}'''</tt></span> }}
{{{syntax|}}}
{{#tag:syntaxhighlight|{{{syntax}}}|lang="nasal"}} }}
{{{text|}}}
{{#if: {{{source|}}}{{{version|}}} | <p>{{#if: {{{source|}}} | {{{source}}}{{#if: {{{version|}}}|&nbsp;&mdash;&nbsp;}} }}{{#if: {{{version|}}} | '''Version added:''' FG {{{version}}} }} {{#if: {{{commit|}}} | ({{{commit}}}) }}</p> }}<!--
;{{{param1|}}}:{{{param1text|}}}
-->{{{text}}}
{{#ifeq: {{{mode|}}} | class | | ;{{{param1|}}}:{{{param1text|}}}
;{{{param2|}}}:{{{param2text|}}}
;{{{param2|}}}:{{{param2text|}}}
;{{{param3|}}}:{{{param3text|}}}
;{{{param3|}}}:{{{param3text|}}}
Line 12: Line 13:
;{{{param9|}}}:{{{param9text|}}}
;{{{param9|}}}:{{{param9text|}}}
;{{{param10|}}}:{{{param10text|}}}
;{{{param10|}}}:{{{param10text|}}}
{{#if: {{{example1|}}}|'''Example{{#if: {{{example2|}}}{{{example3|}}}{{{example4|}}}{{{example5|}}}{{{example6|}}}{{{example7|}}}{{{example8|}}}{{{example9|}}}{{{example10|}}}|s}}'''
{{#if: {{{example1|}}}
{{{example1|}}}{{{example2|}}}{{{example3|}}}{{{example4|}}}{{{example5|}}}{{{example6|}}}{{{example7|}}}{{{example8|}}}{{{example9|}}}{{{example10|}}}}}</includeonly><noinclude>
| '''Example{{#if: {{{example2|}}}|s}}'''<br>
{{{example1text|}}}{{#if: {{{example1|}}} | {{#tag:syntaxhighlight|{{{example1}}}|lang="nasal"|enclose="div"}} }}
{{{example2text|}}}{{#if: {{{example2|}}} | {{#tag:syntaxhighlight|{{{example2}}}|lang="nasal"|enclose="div"}} }}
{{{example3text|}}}{{#if: {{{example3|}}} | {{#tag:syntaxhighlight|{{{example3}}}|lang="nasal"|enclose="div"}} }}
{{{example4text|}}}{{#if: {{{example4|}}} | {{#tag:syntaxhighlight|{{{example4}}}|lang="nasal"|enclose="div"}} }}
{{{example5text|}}}{{#if: {{{example5|}}} | {{#tag:syntaxhighlight|{{{example5}}}|lang="nasal"|enclose="div"}} }}
{{{example6text|}}}{{#if: {{{example6|}}} | {{#tag:syntaxhighlight|{{{example6}}}|lang="nasal"|enclose="div"}} }}
{{{example7text|}}}{{#if: {{{example7|}}} | {{#tag:syntaxhighlight|{{{example7}}}|lang="nasal"|enclose="div"}} }}
{{{example8text|}}}{{#if: {{{example8|}}} | {{#tag:syntaxhighlight|{{{example8}}}|lang="nasal"|enclose="div"}} }}
{{{example9text|}}}{{#if: {{{example9|}}} | {{#tag:syntaxhighlight|{{{example9}}}|lang="nasal"|enclose="div"}} }}
{{{example10text|}}}{{#if: {{{example10|}}} | {{#tag:syntaxhighlight|{{{example10}}}|lang="nasal"|enclose="div"}} }}<!--
-->}} }}</includeonly><noinclude>
{{Informative template|1=
{{Informative template|1=
__NOTOC__
__NOTOC__
Line 20: Line 32:


== Usage ==
== Usage ==
  <nowiki>{{</nowiki>'''Nasal doc'''
  {{obr}}'''Nasal doc'''
  <nowiki>|</nowiki> ''name''        =  
  {{!}} syntax      =
  <nowiki>|</nowiki> ''syntax''      = <nowiki><syntaxhighlight lang="nasal"></syntaxhighlight></nowiki>
{{!}} text        =
  <nowiki>|</nowiki> ''text''       =  
{{!}} ''mode''        =
  <nowiki>|</nowiki> ''param1''      =  
  {{!}} ''source''      =
{{!}} ''version''    =
  {{!}} ''commit''      =
{{!}} ''private''     =
  {{!}} ''param1''      =
  ...
  ...
  <nowiki>|</nowiki> ''param10''    =  
  {{!}} ''param10''    =
  <nowiki>|</nowiki> ''param1text''  =  
  {{!}} ''param1text''  =
  ...
  ...
  <nowiki>|</nowiki> ''param10text'' =  
  {{!}} ''param10text'' =
  <nowiki>|</nowiki> ''example1''   = <nowiki><syntaxhighlight lang="nasal"></syntaxhighlight></nowiki>
  {{!}} ''example1text'' =
{{!}} ''example1''     =
  ...
  ...
  <nowiki>|</nowiki> ''example10''   = <nowiki><syntaxhighlight lang="nasal"></syntaxhighlight></nowiki>
  {{!}} ''example10text'' =
  <nowiki>}}</nowiki>
{{!}} ''example10''     =
  {{cbr}}


All parameters are optional.
All parameters are optional.


=== Basic data ===
=== Basic data ===
; name:          Name of the function (for example '''maketimer''').
; syntax:        Syntax of the function.
; syntax:        Syntax of the function.
:                {{inote|Please use <nowiki><syntaxhighlight></nowiki> tags.}}


; text:          Description of the function.
; text:          Description of the function.


; param(n):     Names of the parameters of the function.  There can be up to ten parameters, from '''param1''' to '''param10'''.
; mode:         If this is set to "class", all parameters except '''source''', '''version''', and '''text''' become unavailable.
 
; source:        When given, should be a [[:Category:Repository link templates|repository link template]], such as {{tl|flightgear file}} with the text as "Source" (see example below). Ideally, a line number should be given as well.
 
; version:      Optional version statement, stating which version of FlightGear the function was added.


; param(n)text: Description of the parameters.  There can be up to ten parameters, from '''param1text''' to '''param10text'''.
; commit:       Optional commit link. If given, the parameter should use one of {{tl|fgdata commit}}, {{tl|flightgear commit}}, or {{tl|simgear commit}} with the link label "commit."


; example(n):   Examples of the usage of the function. There can be up to ten examples, from '''example1''' to '''example10'''.
; private:       The private function behind the function being documented. It is often named the same, but usually has an underscore (<code>_</code>) preceding it. An example is <code>cmdarg()</code> and <code>_cmdarg()</code>.
:                {{inote|Please use <nowiki><syntaxhighlight></nowiki> tags.}}


== Example ==
; param''(n)'':      Names of the parameters of the function. There can be up to ten parameters, from '''param1''' to '''param10'''.
  <nowiki>{{</nowiki>'''Nasal doc'''
<nowiki>|</nowiki> name      = function
<nowiki>| syntax    =
<syntaxhighlight lang="nasal">function(a, [b, c]);</syntaxhighlight></nowiki>
<nowiki>| text      = Returns a value or '''nil'''.</nowiki>
<nowiki>|</nowiki> param1    = a
<nowiki>|</nowiki> param1text = Mandatory argument.
<nowiki>|</nowiki> param2    = b
<nowiki>|</nowiki> param2text = Optional argument.
<nowiki>|</nowiki> param3    = c
<nowiki>|</nowiki> param3text = Optional argument.
<nowiki>| example1  =
<syntaxhighlight lang="nasal">var variable = function("string");</syntaxhighlight></nowiki>
<nowiki>| example2  =
<syntaxhighlight lang="nasal">var variable = function("string", 1.234, FlightGear);</syntaxhighlight></nowiki>
<nowiki>}}</nowiki>


; param''(n)''text:  Description of the parameters.  There can be up to ten parameters, from '''param1text''' to '''param10text'''.
; example''(n)''text: Description of the example.  There can be up to ten of these, from '''example1text''' to '''example10text'''.
; example''(n)'':    Examples of the usage of the function.  There can be up to ten examples, from '''example1''' to '''example10'''.
== Examples ==
<nowiki>=== function() ===</nowiki>
{{obr}}Nasal doc
{{!}} syntax    = function(a, [b, c]);
{{!}} source    = {{flightgear file{{!}}t=Source}}
{{!}} version    = 3.2
{{!}} text      = Returns a value or <nowiki><code>'''nil'''</code></nowiki>.
{{!}} param1    = a
{{!}} param1text = Mandatory argument.
{{!}} param2    = b
{{!}} param2text = Optional argument.
{{!}} param3    = c
{{!}} param3text = Optional argument.
{{!}} example1  = var variable = function("string");
{{!}} example2  = var variable = function("string", 1.234, FlightGear);
{{cbr}}
=== function() ===
{{Nasal doc
{{Nasal doc
| name      = function
| private    = _function()
| syntax    =
| syntax    = function(a, [b, c]);
<syntaxhighlight lang="nasal">function(a, [b, c]);</syntaxhighlight>
| source    = {{flightgear file|t=Source}}
| text      = Returns a value or '''nil'''.
| version    = 3.2
| text      = Returns a value or <code>'''nil'''</code>.
| param1    = a
| param1    = a
| param1text = Mandatory argument.
| param1text = Mandatory argument.
Line 81: Line 108:
| param3    = c
| param3    = c
| param3text = Optional argument.
| param3text = Optional argument.
| example1   =
| example1text   = Example using just one parameter.
<syntaxhighlight lang="nasal">var variable = function("string");</syntaxhighlight>
| example1  = var variable = function("string");
| example2  =
| example2text = Example of the usage of all parameters.
<syntaxhighlight lang="nasal">var variable = function("string", 1.234, FlightGear);</syntaxhighlight>
| example2  = var variable = function("string", 1.234, FlightGear);
}}
}}


You don't have to give examples (although they are encouraged).  You can also change the heading level by adding "="s to the '''name''' argument.
<nowiki>{{</nowiki>'''Nasal doc'''
<nowiki>|</nowiki> name      = =function2=
<nowiki>| syntax    =
<syntaxhighlight lang="nasal">function2();</syntaxhighlight></nowiki>
<nowiki>| text      = Returns a "Hello world!".</nowiki>
<nowiki>}}</nowiki>
{{Nasal doc
| name      = =function2=
| syntax    =
<syntaxhighlight lang="nasal">function2();</syntaxhighlight>
| text      = Returns a "Hello world!".
}}
== Known issues ==
* You have to manually add the <tt><nowiki><syntaxhighlight></nowiki></tt> tags.
* There is a weird issue with the formatting of examples, see [[User:Red Leader/Nasal library functions#setsize]], example 2.
}}
}}


[[Category:Templates]]
[[Category:Templates]]
</noinclude>
</noinclude>

Latest revision as of 19:47, 14 August 2016


The following template description is not displayed when the template is inserted in an article.

Goal

This template is to be used to document Nasal API functions. The underlying aim is to unify Nasal documentation on the wiki.

Usage

{{Nasal doc
| syntax      =
| text        =
| mode        =
| source      =
| version     =
| commit      =
| private     =
| param1      =
...
| param10     =
| param1text  =
...
| param10text  =
| example1text =
| example1     =
...
| example10text =
| example10     =
}}

All parameters are optional.

Basic data

syntax
Syntax of the function.
text
Description of the function.
mode
If this is set to "class", all parameters except source, version, and text become unavailable.
source
When given, should be a repository link template, such as {{flightgear file}} with the text as "Source" (see example below). Ideally, a line number should be given as well.
version
Optional version statement, stating which version of FlightGear the function was added.
commit
Optional commit link. If given, the parameter should use one of {{fgdata commit}}, {{flightgear commit}}, or {{simgear commit}} with the link label "commit."
private
The private function behind the function being documented. It is often named the same, but usually has an underscore (_) preceding it. An example is cmdarg() and _cmdarg().
param(n)
Names of the parameters of the function. There can be up to ten parameters, from param1 to param10.
param(n)text
Description of the parameters. There can be up to ten parameters, from param1text to param10text.
example(n)text
Description of the example. There can be up to ten of these, from example1text to example10text.
example(n)
Examples of the usage of the function. There can be up to ten examples, from example1 to example10.

Examples

=== function() ===
{{Nasal doc
| syntax     = function(a, [b, c]);
| source     = {{flightgear file|t=Source}}
| version    = 3.2
| text       = Returns a value or <code>'''nil'''</code>.
| param1     = a
| param1text = Mandatory argument.
| param2     = b
| param2text = Optional argument.
| param3     = c
| param3text = Optional argument.
| example1   = var variable = function("string");
| example2   = var variable = function("string", 1.234, FlightGear);
}}

function()

_function()
function(a, [b, c]);

Source — Version added: FG 3.2

Returns a value or nil.
a
Mandatory argument.
b
Optional argument.
c
Optional argument.

Examples

Example using just one parameter.
var variable = function("string");
Example of the usage of all parameters.
var variable = function("string", 1.234, FlightGear);