Parameter documentation

  Function parameters have no own special documentation character. They are handled together with the extraction of function. The return value is documented in C and C++ with a C comment between the return type and the function name, in VLisp with a comment between the defun and the closure name. Parameters are documented in C, C++ and VLisp as comments directly after the each parameter declaration. In FORTRAN all comment lines starting with C* after the FUNCTION/SUBROUTINE definition are used for parameter documentation. In this case, the comment is in front of the parameter. Examples can be seen in the language binding section (see Section 6.2.2).

The parameter documentation is parsed for I/O direction at the beginning of the keyword section (between [ and ]). For C and C++ the I/O definition is required, whereas for FORTRAN the default is input and output, which means that every parameter may be modified. An override for input or output only may be specified. For VLisp the default I/O direction is input only since under LISP functions are usually non destructive. Again this may be overridden in the comment. All known I/O directions are listed in Table 6.5.

  
Tabelle 6.5: I/O directions for function parameters

A return value of a function is always an output parameter. After the definition of the I/O direction additional information for language binding may be passed in the keyword section within the [ and ]. This information is used depending on the target-domain of Create-TAC-Interface. All keys with their associated function in the target domains are:

:opt target domain VLisp
Optional parameter in binding

:default target domain VLisp
The default value of an optional parameter in binding. The type must correspond to the function parameter and is used, if the optional parameter is not specified on function calls.

:key target domain VLisp
Implement the optional parameter as a position independent LISP key instead of an positional optional parameter.

:symbol target domain VLisp
The value of the parameter can be given symbolically in VLisp, that means a LISP symbol instead of the value. The value is allowed as parameter too.

:min target domain VLisp
The minimum value of the parameter. For derived parameters (key der) this means the associated array must have a minimum size.

:max target domain VLisp
The maximum value of the parameter. For derived parameters (key der) this means the associated array is not allowed to be larger than this value.

:oneof target domain VLisp
The value is part of an enumeration like constant. This must be used if the type of the enumeration type is not used by TAC, e.g., C constants defined with #define and combined with element.

:set target domain VLisp
The value is a combination of some integer values. These constants must be defined with the element key.

:der target domain VLisp
This parameter can be derived from the length of another array parameter.

:index target domain FORTRAN C
This parameter is an index into an array (or an array of indices) and needs index transformation.

:size target domain VLisp FORTRAN C
Gives the real size of an output array. Mostly used in combination with the key maxsize if an array must be given on input and is partly filled from the function. The calculation of the size is given by:

1. a constant value,
2. an integer parameter of the function,
3. an expression with `+' for addition of two values,
4. an expression with `*' for multiplication of two values,
5. an expression with `[+]' for summing up all values of an integer array parameter,
6. an expression with `[*]' for multiplying all values of an integer array parameter.

:maxsize target domain VLisp FORTRAN C
The array required as input may be used up to this maximum size in the function. The real size may be given by a parameter with the key size.

:callback target domain VLisp FORTRAN
The parameter is a callback function (see Section A.1). This means this parameter function is be called from within the function or is registered for asynchronous activation based on an event.

:local target domain VLisp
The callback parameter is used only local to the function and needs no global protection in VLisp (only during the C/C++ function call).

:once target domain VLisp
The callback parameter is only called once and can then be removed from the garbage collection protection of VLisp.

:type target domain VLisp FORTRAN
Sets the type of the parameter to be compatible with the given type. Must be given, if the type of the parameter is not known by TAC.

:constant target domain VLisp
The parameter is not modified by the function.

:allocated target domain VLisp
The memory used by the output parameter has been allocated and is not a statically allocated array.

:check target domain VLisp
This parameter can be cross checked against other parameters by using the expression following the key, e.g., multiple arrays with the same length. The same expression mechanism as for the key size can be used.

:ok target domain VLisp FORTRAN
The function was only successful, if the return value is identical to the given value else it is assumed to have failed. In case of VLisp the return value is then ignored.

:not-ok target domain VLisp FORTRAN
The function failed if the value of the output parameter or the return value is identical to the given value. Otherwise the return value is handled like an output parameter.

:noerror target domain FORTRAN
Do not create an additional error return parameter in FORTRAN/C binding which is usually created to inform the FORTRAN caller about the status of the function call.

:readonly target domain VLisp
Is used to define that a C++ object variable is not allowed to be modified, but accessible to VLisp.