9.3. Synopsis de fonction

FuncSynopsis = ( FuncSynopsisInfo | FuncPrototype )+

FuncPrototype = ( FuncDef,
                  ( Void | VarArgs | ParamDef+ )
                )

FuncDef = ( ( #PCDATA
              | Replaceable
              | Function
            )*
          )

ParamDef = ( (#PCDATA
               | Replaceable
               | Parameter
               | FuncParams
             )*
           )

Éléments : FuncSynopsis, FuncSynopsisInfo, FuncPrototype, FuncDef, Void, VarArgs, ParamDef, Replaceable, Function, Parameter, FuncParams.

L'élément FuncSynopsis permet de donner la définition, ou synopsis, d'une ou plusieurs fonctions. Le modèle de contenu de cet élément a été conçu pour définir des fonctions du langage C, et pourra ne pas être adapté pour définir des fonctions d'autres langages. Pour des langages orientés objet, on pourra utiliser l'élément ClassSynopsis. Pour d'autres langages, on pourra utiliser l'élément plus générique Synopsis.

Il n'est pas nécessaire de fournir la ponctuation et la mise en page pour le rendu final de la définition de la fonction. L'auteur pourra prendre soin à baliser la définition de fonction de sorte que le système de traitement soit capable de générer une définition aussi bien au format K&R que ANSI (ou autres).

L'élément FuncSynopsis est constitué d'un ou plusieurs des éléments suivants, dans un ordre quelconque :

• d'informations complétant les définitions de fonctions (FuncSynopsisInfo),

• d'un prototype de fonction (FuncPrototype).

Les informations complétant les définitions de fonctions FuncSynopsisInfo, contrairement aux autres éléments d'information, ne décrivent pas de métainformations. Dans ce cas spécial, elles fournissent des informations relatives à la définition de la fonction, qui apparaîtront dans un environnement verbatim. Cet élément pourra par exemple contenir les fichiers d'en-tête à inclure pour utiliser cette fonction.

<funcsynopsis>
  <funcsynopsisinfo>#include &lt;math.h&gt;</funcsynopsisinfo>
  <funcprototype>
    <funcdef>double <function>cos</function></funcdef>
    <paramdef>double <parameter>x</parameter></paramdef>
  </funcprototype>
</funcsynopsis>

Un prototype de fonction FuncPrototype permet de définir une fonction et ses arguments. Il est constitué :

• du nom de la fonction et du type de retour de la fonction (FuncDef),

• de la définition des arguments de la fonction, qui peut être l'un des éléments suivants :

  • Void si la fonction n'accepte aucun argument,

  • VarArgs si la fonction accepte un nombre variable d'arguments,

  • un ou plusieurs ParamDef, chacun définissant un paramètre de la fonction.

À l'intérieur de l'élément FuncDef, utilisez l'élément Function pour déclarer le nom de la fonction, et donnez le type de retour de la fonction directement dans l'élément FuncDef. Par exemple, la fonction cos retournant une valeur de type double sera notée :

<funcdef>double <function>cos</function></funcdef>

De même, à l'intérieur de l'élément ParamDef, utilisez l'élément Parameter pour déclarer le nom du paramètre, et donnez le type du paramètre directement dans l'élément ParamDef. Par exemple, l'argument x de la fonction cos étant de type double, il sera noté :

<paramdef>double <parameter>x</parameter></paramdef>

Dans les éléments FuncDef et ParamDef, vous pouvez utiliser l'élément Replaceable pour indiquer que le contenu doit être remplacé par l'utilisateur.

Si un paramètre de la fonction est un pointeur vers une fonction prenant des paramètres, vous pouvez préciser les paramètres de cette fonction à l'aide de l'élément FuncParams, à l'intérieur de ParamDef. Contrairement aux autres éléments du contenu de FuncPrototype, le contenu de FuncParams doit inclure la ponctuation. Par exemple, pour définir que la fonction prend trois paramètres de type int, utilisez :

<funcparams>int, int, int</funcparams>

Notez qu'il n'est pas possible d'indiquer efficacement que le type de retour d'une fonction est un pointeur de fonction. Pour cela, vous pourrez déclarer un type grâce à typedef puis utiliser ce nouveau type comme type de retour de la fonction dans le prototype de la fonction.

Si la fonction prend un nombre variable d'arguments sans qu'elle ait d'arguments fixes, utilisez l'élément VarArgs seul pour décrire les arguments de la fonction. Au contraire, si la fonction a un certain nombre d'arguments fixes suivis d'un nombre variable d'arguments, utilisez ParamDef pour décrire les arguments fixes puis <paramdef>...</paramdef> pour indiquer que le nombre d'arguments finals est variable.

<funcsynopsis>
  <funcsynopsisinfo>#include &lt;unistd.h&gt;</funcsynopsisinfo>
  <funcprototype>
    <funcdef>int <function>pause</function></funcdef>
    <void>
  </funcprototype>

  <funcsynopsisinfo>#include &lt;signal.h&gt;</funcsynopsisinfo>
  <funcprototype>
    <funcdef>int <function>raise</function></funcdef>
    <paramdef>int <parameter>sig</parameter></paramdef>
  </funcprototype>

  <funcsynopsisinfo>#include &lt;signal.h&gt;</funcsynopsisinfo>
  <funcsynopsisinfo>typedef void (*<type>__sighandler_t</type
>) (int);</funcsynopsisinfo>
  <funcprototype>
    <funcdef>__sighandler_t <function>signal</function></funcdef>
    <paramdef>int <parameter>signum</parameter></paramdef>
    <paramdef>void (*<parameter>handler</parameter
>)<funcparams>int</funcparams></paramdef>
  </funcprototype>

  <funcsynopsisinfo>#include &lt;stdio.h&gt;</funcsynopsisinfo>
  <funcprototype>
    <funcdef>int <function>printf</function></funcdef>
    <paramdef>const char *<parameter>format</parameter></paramdef>
    <paramdef>...</paramdef>
  </funcprototype>

  <funcsynopsisinfo>#include "mes_maths.h"</funcsynopsisinfo>
  <funcprototype>
    <funcdef>double <function>moyenne</function></funcdef>
    <varargs>
  </funcprototype>
</funcsynopsis>

<funcsynopsis>
  <funcprototype>
    <funcdef><replaceable>type</replaceable> <function
><replaceable>fonction</replaceable></function></funcdef>
    <paramdef><replaceable>type</replaceable> <parameter
><replaceable>paramètre</replaceable></parameter></paramdef>
  </funcprototype>
</funcsynopsis>