JezK
Edit File: Typed-Functions.html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ --> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <!-- This manual is for GNU Texinfo (version 6.8, 8 June 2021), a documentation system that can produce both online information and a printed manual from a single source using semantic markup. Copyright (C) 1988, 1990-1993, 1995-1999, 2001-2021 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". --> <title>Typed Functions (GNU Texinfo 6.8)</title> <meta name="description" content="Typed Functions (GNU Texinfo 6.8)"> <meta name="keywords" content="Typed Functions (GNU Texinfo 6.8)"> <meta name="resource-type" content="document"> <meta name="distribution" content="global"> <meta name="Generator" content="texi2any"> <meta name="viewport" content="width=device-width,initial-scale=1"> <link href="index.html" rel="start" title="Top"> <link href="Command-and-Variable-Index.html" rel="index" title="Command and Variable Index"> <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> <link href="Def-Cmds-in-Detail.html" rel="up" title="Def Cmds in Detail"> <link href="Typed-Variables.html" rel="next" title="Typed Variables"> <link href="Variables-Commands.html" rel="prev" title="Variables Commands"> <style type="text/css"> <!-- a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em} a.summary-letter {text-decoration: none} blockquote.indentedblock {margin-right: 0em} div.display {margin-left: 3.2em} div.example {margin-left: 3.2em} kbd {font-style: oblique} pre.display {font-family: inherit} pre.format {font-family: inherit} pre.menu-comment {font-family: serif} pre.menu-preformatted {font-family: serif} span.nolinebreak {white-space: nowrap} span.roman {font-family: initial; font-weight: normal} span.sansserif {font-family: sans-serif; font-weight: normal} span:hover a.copiable-anchor {visibility: visible} ul.no-bullet {list-style: none} --> </style> </head> <body lang="en"> <div class="subsection" id="Typed-Functions"> <div class="header"> <p> Next: <a href="Typed-Variables.html" accesskey="n" rel="next">Variables in Typed Languages</a>, Previous: <a href="Variables-Commands.html" accesskey="p" rel="prev">Variables and Similar Entities</a>, Up: <a href="Def-Cmds-in-Detail.html" accesskey="u" rel="up">The Definition Commands</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Command-and-Variable-Index.html" title="Index" rel="index">Index</a>]</p> </div> <hr> <span id="Functions-in-Typed-Languages"></span><h4 class="subsection">13.5.3 Functions in Typed Languages</h4> <span id="index-Typed-functions"></span> <span id="index-Functions_002c-in-typed-languages"></span> <p>The <code>@deftypefn</code> 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++. </p> <dl compact="compact"> <dd><span id="index-deftypefn"></span> </dd> <dt><span><code>@deftypefn <var>category</var> <var>data-type</var> <var>name</var> <var>arguments</var>…</code></span></dt> <dd><p>The <code>@deftypefn</code> command is the general definition command for functions and similar entities that may take arguments and that are typed. The <code>@deftypefn</code> 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. </p> <p>For example, </p> <div class="example"> <pre class="example">@deftypefn {Library Function} int foobar @ (int @var{foo}, float @var{bar}) … @end deftypefn </pre></div> <p>produces: </p> <blockquote> <dl class="def"> <dt id="index-foobar-1"><span class="category">Library Function: </span><span><em>int</em> <strong>foobar</strong> <em>(int <var>foo</var>, float <var>bar</var>)</em><a href='#index-foobar-1' class='copiable-anchor'> ¶</a></span></dt> <dd><p>… </p></dd></dl> </blockquote> <p>This means that <code>foobar</code> is a “library function” that returns an <code>int</code>, and its arguments are <var>foo</var> (an <code>int</code>) and <var>bar</var> (a <code>float</code>). </p> <p>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 <code>@var</code> for the variable names, which will uppercase the variable names in Info and use the slanted typewriter font in printed output; (c) use <code>@var</code> for the variable names and <code>@code</code> for the type names and keywords, which will be dutifully obeyed. </p> <p>The template for <code>@deftypefn</code> is: </p> <div class="example"> <pre class="example">@deftypefn <var>category</var> <var>data-type</var> <var>name</var> <var>arguments</var> … <var>body-of-description</var> @end deftypefn </pre></div> <p>Note that if the <var>category</var> or <var>data type</var> is more than one word then it must be enclosed in braces to make it a single argument. </p> <p>If you are describing a procedure in a language that has packages, such as Ada, you might consider using <code>@deftypefn</code> in a manner somewhat contrary to the convention described in the preceding paragraphs. For example: </p> <div class="example"> <pre class="example">@deftypefn stacks private push @ (@var{s}:in out stack; @ @var{n}:in integer) … @end deftypefn </pre></div> <p>(In these examples the <code>@deftypefn</code> arguments are shown using continuations (see <a href="Def-Cmd-Continuation-Lines.html">Definition Command Continuation Lines</a>), but could be on a single line.) </p> <p>In this instance, the procedure is classified as belonging to the package <code>stacks</code> rather than classified as a ‘procedure’ and its data type is described as <code>private</code>. (The name of the procedure is <code>push</code>, and its arguments are <var>s</var> and <var>n</var>.) </p> <p><code>@deftypefn</code> creates an entry in the index of functions for <var>name</var>. </p> </dd> <dt id='index-deftypefun'><span><code>@deftypefun <var>data-type</var> <var>name</var> <var>arguments</var>…</code><a href='#index-deftypefun' class='copiable-anchor'> ¶</a></span></dt> <dd><p>The <code>@deftypefun</code> command is the specialized definition command for functions in typed languages. The command is equivalent to ‘<samp>@deftypefn Function …</samp>’. The template is: </p> <div class="example"> <pre class="example">@deftypefun <var>type</var> <var>name</var> <var>arguments</var>… <var>body-of-description</var> @end deftypefun </pre></div> <p><code>@deftypefun</code> creates an entry in the index of functions for <var>name</var>. </p> </dd> </dl> <span id="index-Return-type_002c-own-line-for"></span> <span id="index-deftypefnnewline"></span> <p>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: <code>@deftypefnnewline on</code>. </p> <p>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 <code>@deftypeop</code> and <code>@deftypemethod</code> (see <a href="Object_002dOriented-Methods.html">Object-Oriented Methods</a>). </p> <p>Specifying <code>@deftypefnnewline off</code> reverts to the default. </p> </div> <hr> <div class="header"> <p> Next: <a href="Typed-Variables.html">Variables in Typed Languages</a>, Previous: <a href="Variables-Commands.html">Variables and Similar Entities</a>, Up: <a href="Def-Cmds-in-Detail.html">The Definition Commands</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Command-and-Variable-Index.html" title="Index" rel="index">Index</a>]</p> </div> </body> </html>