Template:Nasal doc: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
m (Add enclose="div")
(Add a "private function" (e.g., _cmdarg();) parameter; sort out examples)
Line 1: Line 1:
<includeonly>{{#tag:syntaxhighlight|{{{syntax}}}|lang="nasal"}}
<includeonly>{{#if: {{{private|}}} | :<span style="color:grey">'''{{{private}}}'''</span> }}
{{#tag:syntaxhighlight|{{{syntax}}}|lang="nasal"}}
{{#if: {{{source|}}}{{{version|}}} | <p>{{#if: {{{source|}}} | {{{source}}}{{#if: {{{version|}}}|&nbsp;&mdash;&nbsp;}} }}{{#if: {{{version|}}} | '''Version added:''' FG {{{version}}} }}</p> }}<!--
{{#if: {{{source|}}}{{{version|}}} | <p>{{#if: {{{source|}}} | {{{source}}}{{#if: {{{version|}}}|&nbsp;&mdash;&nbsp;}} }}{{#if: {{{version|}}} | '''Version added:''' FG {{{version}}} }}</p> }}<!--
-->{{{text}}}
-->{{{text}}}
Line 31: Line 32:


== Usage ==
== Usage ==
  {{obr}}'''nasal doc'''
  {{obr}}'''Nasal doc'''
  {{!}} syntax      =
  {{!}} syntax      =
  {{!}} text        =
  {{!}} text        =
Line 37: Line 38:
  {{!}} ''line''        =
  {{!}} ''line''        =
  {{!}} ''version''    =
  {{!}} ''version''    =
{{!}} ''private''    =
  {{!}} ''param1''      =
  {{!}} ''param1''      =
  ...
  ...
Line 60: Line 62:


; version:      Optional version statement, sating which version of FlightGear the function was added.
; version:      Optional version statement, sating which version of FlightGear the function was added.
; private:      The private function behind the function being documented. It is often named the same, but has an underscore (<code>_</code>) proceeding it. An example is <code>cmdarg()</code> and <code>_cmdarg()</code>.


; param''(n)'':      Names of the parameters of the function.  There can be up to ten parameters, from '''param1''' to '''param10'''.
; param''(n)'':      Names of the parameters of the function.  There can be up to ten parameters, from '''param1''' to '''param10'''.
Line 70: Line 74:


== Examples ==
== Examples ==
  <nowiki>== function() ==</nowiki>
=== Common usage ===
  <nowiki>==== function() ====</nowiki>
  {{obr}}nasal doc
  {{obr}}nasal doc
  {{!}} syntax    = function(a, [b, c]);
  {{!}} syntax    = function(a, [b, c]);
  {{!}} version     = 3.2
  {{!}} version   = 3.2
  {{!}} text      = Returns a value or <nowiki><code>'''nil'''</code></nowiki>.
  {{!}} text      = Returns a value or <nowiki><code>'''nil'''</code></nowiki>.
  {{!}} param1    = a
  {{!}} param1    = a
Line 85: Line 90:
  {{cbr}}
  {{cbr}}


=== function() ===
==== function() ====
{{nasal doc
{{nasal doc
| syntax    = function(a, [b, c]);
| syntax    = function(a, [b, c]);
Line 99: Line 104:
| example2  = var variable = function("string", 1.234, FlightGear);
| example2  = var variable = function("string", 1.234, FlightGear);
}}
}}
<br>
 
----
=== No examples given ===
<br>
You don't have to give examples (although they are encouraged).
You don't have to give examples (although they are encouraged).
  <nowiki>=== function() ===</nowiki>
  <nowiki>==== function() ====</nowiki>
  {{obr}}nasal doc
  {{obr}}nasal doc
  {{!}} syntax    = function2();
  {{!}} syntax    = function2();
Line 109: Line 113:
  {{cbr}}
  {{cbr}}


=== function() ===
==== function() ====
{{nasal doc
{{nasal doc
| name      = function2
| name      = function2
Line 115: Line 119:
| text      = Returns "Hello world!".
| text      = Returns "Hello world!".
}}
}}
<br>
 
----
=== Source parameter given ===
<br>
You can add a source parameter to link to the source code behind the function.
You can add a source parameter to link to the source code behind the function.
  <nowiki>=== getprop() ===
  <nowiki>==== getprop() ====</nowiki>
  {{obr}}nasal doc
  {{obr}}nasal doc
  {{!}} syntax    = getprop(path);
  {{!}} syntax    = getprop(path);
  {{!}} text      = Gets add returns the value of a node in the [[Property Tree]].
  {{!}} text      = Gets add returns the value of a node in the <nowiki>[[Property Tree]]</nowiki>.
  {{!}} source    = {{flightgear file|src/Scripting/NasalSys.cxx|l=l345|t=Source}}
  {{!}} source    = <nowiki>{{flightgear file|src/Scripting/NasalSys.cxx|l=l345|t=Source}}</nowiki>
  {{cbr}}</nowiki>
  {{cbr}}


=== getprop() ===
==== getprop() ====
{{nasal doc
{{nasal doc
|syntax    = getprop(path);
|syntax    = getprop(path);

Revision as of 14:33, 18 October 2015


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        =
| source      =
| line        =
| version     =
| 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.
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, sating which version of FlightGear the function was added.
private
The private function behind the function being documented. It is often named the same, but has an underscore (_) proceeding 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

Common usage

==== function() ====
{{nasal doc
| syntax     = function(a, [b, c]);
| 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(a, [b, c]);

Version added: FG 3.2

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

Examples 

var variable = function("string");
var variable = function("string", 1.234, FlightGear);

No examples given

You don't have to give examples (although they are encouraged). 

==== function() ====
{{nasal doc
| syntax     = function2();
| text       = Returns "Hello world!".
}}

function()

function2();

Returns "Hello world!".


Source parameter given

You can add a source parameter to link to the source code behind the function. 

==== getprop() ====
{{nasal doc
| syntax     = getprop(path);
| text       = Gets add returns the value of a node in the [[Property Tree]].
| source     = {{flightgear file|src/Scripting/NasalSys.cxx|l=l345|t=Source}}
}}

getprop()

getprop(path);

Source

Gets add returns the value of a node in the Property Tree.


Retrieved from "https://wiki.flightgear.org/w/index.php?title=Template:Nasal_doc&oldid=88732"