---

13.6.2 Functions in Typed Languages ¶

The @deftypefn command and its variants are generic commands for describing functions. They are particularly suitable for languages in which you must declare types of variables and functions, such as C and C++.

@deftypefn category data-type name arguments… ¶

The @deftypefn command is the general definition command for functions and similar entities that may take arguments and that could be typed. The @deftypefn command is written at the beginning of a line and is followed on the same line by the category of entity being described, information on the returned value, the name of this particular entity, and its arguments, if any.

For example,

@deftypefn {Library Function} int foobar @
  (int @var{foo}, float @var{bar})
...
@end deftypefn

produces:

Library Function: int foobar (int foo, float bar) ¶

…

This means that foobar is a “library function” that returns an int, and its arguments are foo (an int) and bar (a float). ‘Library Function’ has to be enclosed in braces to make it a single argument.

When using @deftypefn command and variations, you should mark parameter names with @var to distinguish these from data type names, keywords, and other parts of the literal syntax of the programming language. Where the output format allows, all output on the definition line is in a typewriter font by default. @var uses an appropriate font where it occurs.

If you are describing a procedure in a language that has packages, such as Ada, you might consider using @deftypefn in the following manner:

@deftypefn stacks private push @
       (@var{s}:in out stack; @
       @var{n}:in integer)
...
@end deftypefn

(In these examples the @deftypefn arguments are shown using continuations (see Definition Command Continuation Lines), but could be on a single line.)

In this instance, the procedure is classified as belonging to the package stacks rather than classified as a ‘procedure’ and its data type is described as private. (The name of the procedure is push, and its arguments are s and n.) Output:

stacks: private push (s:in out stack; n:in integer) ¶

…

@deftypefn and variants could be used when it is convenient to interpret the arguments list as literal computer code, marking argument names with @var. It is not necessary for any type names to appear, and you can give an empty return type as ‘{}’.

The information on return values may be used to name the return variables. For example, in Perl, returned scalars may be given the $result and $status name in the following manner:

@deftypefn {Sub} {(@var{$result}, @var{$status} =)} @
                     process (@var{$input})
... Set @var{$status} to 0 in case of failure ...
@end deftypefn

to get output like

Sub: ($result, $status) = process ($input) ¶

… Set $status to 0 in case of failure …

@deftypefn creates an entry in the index of functions for name.

@deftypefun data-type name arguments… ¶

The @deftypefun command is the specialized definition command for functions. The command is equivalent to ‘@deftypefn Function …’.

@deftypefun creates an entry in the index of functions for name.

Ordinarily, the return type is printed on the same line as the function name and arguments, as shown above. In source code, GNU style for typed functions is to put the return type on a line by itself. So Texinfo provides an option to do that: @deftypefnnewline on.

This affects the generic functions only—not untyped functions with simple arguments such as @deffn, not typed variables, etc. Specifically, it affects the commands in this section, and the analogous commands for object-oriented languages, namely @deftypeop and @deftypemethod (see Object-Oriented Methods).

Specifying @deftypefnnewline off reverts to the default.