texinfo: Typed Functions

Def Cmds in Detail

Typed Variables

Variables Commands

Back to Software Index

16.5.3 Functions in Typed Languages
-----------------------------------

The '@deftypefn' command and its variations are for describing functions
in 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 are
     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, the type of 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').

     Since in typed languages, the actual names of the arguments are
     typically scattered among data type names and keywords, Texinfo
     cannot find them without help.  You can either (a) write everything
     as straight text, and it will be printed in slanted type; (b) use
     '@var' for the variable names, which will uppercase the variable
     names in Info and use the slanted typewriter font in printed
     output; (c) use '@var' for the variable names and '@code' for the
     type names and keywords, which will be dutifully obeyed.

     The template for '@deftypefn' is:

          @deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS ...
          BODY-OF-DESCRIPTION
          @end deftypefn

     Note that if the CATEGORY or DATA TYPE is more than one word then
     it must be enclosed in braces to make it a single argument.

     If you are describing a procedure in a language that has packages,
     such as Ada, you might consider using '@deftypefn' in a manner
     somewhat contrary to the convention described in the preceding
     paragraphs.  For example:

          @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 (Note: Def Cmd 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.)

     '@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 in typed languages.  The command is equivalent to
     '@deftypefn Function ...'.  The template is:

          @deftypefun TYPE NAME ARGUMENTS...
          BODY-OF-DESCRIPTION
          @end deftypefun

     '@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
is to put the return type on a line by itself.  So Texinfo provides an
option to do that: '@deftypefnnewline on'.

  This affects typed functions only--not untyped functions, not typed
variables, etc..  Specifically, it affects the commands in this section,
and the analogous commands for object-oriented languages, namely
'@deftypeop' and '@deftypemethod' (Note: Object-Oriented Methods).

  Specifying '@deftypefnnewline off' reverts to the default.