Documenter le code

---

Ce chapitre couvre deux sujets :

1. Comment placer des commentaires dans votre code de manière à ce que Doxygen les incorpore dans la documentation qu'il génère. Ceci est détaillé plus en détail dans la section ci-dessous.

2. Manière de structurer le contenu d'un bloc de commentaires de manière à ce que le résultat soit beau, comme expliqué dans la section Anatomie d'un bloc de commentaires.

Blocs de commentaires spéciaux

Un bloc de commentaires spécial est un bloc de commentaires de style C ou C++ avec quelques marquages ​​supplémentaires, afin que Doxygen sache qu'il s'agit d'un morceau de texte structuré qui doit se retrouver dans la documentation générée. La section suivante présente les différents styles pris en charge par Doxygen.

Pour le code Python, VHDL et Fortran, il existe différentes conventions de commentaires, que vous trouverez respectivement dans les sections Blocs de commentaires en Python, Blocs de commentaires en VHDL et Blocs de commentaires en Fortran.

Blocs de commentaires pour les langages de type C (C/C++/C#/Objective-C/PHP/Java)

Pour chaque entité du code, il existe deux (ou dans certains cas trois) types de descriptions, qui forment ensemble la documentation de cette entité ; une brève description et une description détaillée, toutes deux facultatives. Pour les méthodes et les fonctions, il existe également un troisième type de description, la description dite dans le corps, qui consiste en la concaténation de tous les blocs de commentaires trouvés dans le corps de la méthode ou de la fonction.

Il est permis d'avoir plus d'une description brève ou détaillée (mais ce n'est pas recommandé, car l'ordre dans lequel les descriptions apparaîtront n'est pas spécifié).

Comme son nom l'indique, une brève description est une courte ligne, tandis que la description détaillée fournit une documentation plus longue et plus détaillée. Une description « dans le corps » peut également servir de description détaillée ou peut décrire un ensemble de détails d'implémentation. Pour la sortie HTML, les brèves descriptions sont également utilisées pour fournir des info-bulles aux endroits où un élément est référencé.

Il existe plusieurs façons de marquer un bloc de commentaires comme une description détaillée :

1 . Vous pouvez utiliser le style Javadoc, qui consiste en un bloc de commentaires de style C commençant par deux *, comme ceci :

/**
 * ... text ...
 */

2 . ou vous pouvez utiliser le style Qt et ajouter un point d'exclamation (!) après l'ouverture d'un bloc de commentaires de style C, comme illustré dans cet exemple :

/*!
 * ... text ...
 */

Dans les deux cas, les * intermédiaires sont facultatifs, donc

/*!
 * ... text ...
 */

est également valide.

3 . Une troisième alternative consiste à utiliser un bloc d'au moins deux lignes de commentaires C++, où chaque ligne commence par une barre oblique supplémentaire ou un point d'exclamation. Voici des exemples des deux cas :

///
/// ... text ...
///

ou

//!
//!... text ...
//!

Notez qu'une ligne vide termine un bloc de documentation dans ce cas.

4 . Certaines personnes aiment rendre leurs blocs de commentaires plus visibles dans la documentation. Pour cela, vous pouvez utiliser ce qui suit :

/*******************************************//**
 *  ... text
 ***********************************************/

Remarque : les 2 barres obliques pour terminer le bloc de commentaires normal et démarrer un bloc de commentaires spécial.

Remarque : soyez prudent lorsque vous utilisez un reformateur comme clang-format car il peut considérer ce type de commentaire comme 2 commentaires distincts et introduire un espacement entre eux.

ou

/////////////////////////////////////////////////
/// ... text ...
/////////////////////////////////////////////////

ou

/***********************************************
 *  ... text
 ***********************************************/

tant que JAVADOC_BANNER est défini sur YES.

/**
* Un bref historique des commentaires de style JavaDoc (style C).
*
* Il s'agit du commentaire de style C de style JavaDoc typique. Il commence par deux
* astérisques.
*
* @param theory Même s'il n'existe qu'une seule théorie unifiée possible. c'est juste un
* ensemble de règles et d'équations.
*/
void cstyle( int theory );

/*********************************************************************************
* Un bref historique des commentaires de bannière de style JavaDoc (style C).
*
* Il s'agit du commentaire de "bannière" de style JavaDoc de style C typique. Il commence 
* par une barre oblique suivie d'un certain nombre, n, d'astérisques, où n > 2. Il est
* écrit de cette façon pour être plus "visible" pour les développeurs qui lisent le
* code source.
*
* Souvent, les développeurs ne savent pas qu'il ne s'agit pas (par défaut) d'un bloc 
* de commentaires Doxygen valide !
*
* Cependant, tant que JAVADOC_BANNER = YES est ajouté au fichier Doxy, il
* fonctionnera comme prévu.
*
* Ce style de commentaire se comporte bien avec le format clang.
*
* @param theory Même s'il n'y a qu'une seule théorie unifiée possible. ce n'est qu'un
* ensemble de règles et d'équations.
**********************************************************************************/
void javadocBanner( int theory );

/******************************************************************************//**
* Un bref historique des commentaires de bannière de style Doxygen.
*
* Il s'agit d'un commentaire de "bannière" de style C de style Doxygen. Il commence par un
* commentaire "normal" et est ensuite converti en un bloc de commentaires "spécial" 
* vers la fin de la première ligne. Il est écrit de cette façon pour être plus "visible" 
* pour les développeurs qui lisent le code source.
* Ce style de commentaire se comporte mal avec le format clang.
*
* @param theory Même s'il n'y a qu'une seule théorie unifiée possible. ce n'est qu'un
* ensemble de règles et d'équations.
*******************************************************************************/
void doxygenBanner( int theory );

Cliquez ici pour accéder à la documentation HTML correspondante générée par Doxygen.

Pour la brève description, il existe également plusieurs possibilités :

On peut utiliser la commande \brief avec l'un des blocs de commentaires ci-dessus. Cette commande se termine à la fin d'un paragraphe, de sorte que la description détaillée suit après une ligne vide.

Voici un exemple :

/*! \brief Brève description.
* Suite de la brève description.
*
* La description détaillée commence ici.
*/

Si JAVADOC_AUTOBRIEF est défini sur YES dans le fichier de configuration, l'utilisation de blocs de commentaires de style Javadoc démarrera automatiquement une brève description qui se termine au premier point, point d'interrogation ou point d'exclamation suivi d'un espace ou d'une nouvelle ligne. Voici un exemple :

/** Brève description qui se termine à ce point. Les détails suivent
* ici.
*/

L'option a le même effet pour les commentaires C++ spéciaux sur plusieurs lignes :

/// Brève description qui se termine à ce point. Les détails suivent
/// ici.

Une troisième option consiste à utiliser un commentaire spécial de style C++ qui ne s'étend pas sur plus d'une ligne. Voici deux exemples :

/// Brève description.
/** Description détaillée. */

ou

//! Brève description.

//! Description détaillée
//! commence ici.

Notez la ligne vide dans le dernier exemple, qui est nécessaire pour séparer la brève description du bloc contenant la description détaillée. Le JAVADOC_AUTOBRIEF doit également être défini sur NO dans ce cas.

Comme vous pouvez le voir, Doxygen est assez flexible. Si vous avez plusieurs descriptions détaillées, comme dans l'exemple suivant :

//! Brève description, qui est
//! vraiment une description détaillée puisqu'elle s'étend sur plusieurs lignes.
/*! Une autre description détaillée !
*/

Elles seront jointes. Notez que c'est également le cas si les descriptions se trouvent à différents endroits du code ! Dans ce cas, l'ordre dépendra de l'ordre dans lequel Doxygen analyse le code.

Contrairement à la plupart des autres systèmes de documentation, Doxygen vous permet également de placer la documentation des membres (y compris les fonctions globales) devant la définition. De cette façon, la documentation peut être placée dans le fichier source au lieu du fichier d'en-tête. Cela permet de conserver la compacité du fichier d'en-tête et de permettre à l'implémenteur des membres d'accéder plus directement à la documentation. En guise de compromis, la brève description pourrait être placée avant la déclaration et la description détaillée avant la définition du membre.

Placer la documentation après les membres

Si vous souhaitez documenter les membres d'un fichier, d'une structure, d'une union, d'une classe ou d'une énumération, il est parfois souhaitable de placer le bloc de documentation après le membre plutôt qu'avant. Pour cela, vous devez placer un marqueur "<" supplémentaire dans le bloc de commentaires. Notez que cela fonctionne également pour les paramètres d'une fonction.

Voici quelques exemples :

int var ; /*!< Description détaillée après le membre */

Ce bloc peut être utilisé pour placer un bloc de documentation détaillée de style Qt après un membre. D'autres façons de faire la même chose sont :

int var ; /**< Description détaillée après le membre */

ou

int var ; //!< Description détaillée après le membre
//!<

ou

int var ; ///< Description détaillée après le membre
///<

Le plus souvent, on ne souhaite placer qu'une brève description après un membre. Cela se fait comme suit :

int var ; //!< Brève description après le membre

ou

int var ; ///< Brève description après le membre

Pour les fonctions, on peut utiliser la commande @param pour documenter les paramètres, puis utiliser [in], [out], [in,out] pour documenter la direction. Pour la documentation en ligne, cela est également possible en commençant par l'attribut direction, par exemple

void foo(int v /**< [in] docs for input parameter v. */);

Notez que ces blocs ont la même structure et la même signification que les blocs de commentaires spéciaux de la section précédente, sauf que le "<" indique que le membre est situé devant le bloc au lieu d'être après le bloc.

Voici un exemple d'utilisation de ces blocs de commentaires :

/*! Une classe de test */

class Afterdoc_Test
{
  public:
    /** Un type d'énumération.
      * Le bloc de documentation ne peut pas être placé après l'énumération !
      */
  enum EnumType
  {
    int EVal1, /**< valeur d'énumération 1 */
    int EVal2 /**< valeur d'énumération 2 */
  };
  void member(); //!< une fonction membre.

  protected:
    int value; /*!< une valeur entière */
};

Cliquez ici pour accéder à la documentation HTML correspondante générée par Doxygen.

Exemples

Voici un exemple d'un morceau de code C++ documenté utilisant le style Qt :

//! Une classe de test.
/*!
Une description de classe plus élaborée.
*/

class QTstyle_Test
{
    public:

    //! Une énumération.
    /*! Description d'énumération plus détaillée. */
    enum TEnum {
      TVal1, /*!< Valeur d'énumération TVal1. */
      TVal2, /*!< Valeur d'énumération TVal2. */
      TVal3 /*!< Valeur d'énumération TVal3. */
    }
              //! Pointeur d'énumération.
              /*! Détails. */
              *enumPtr,
              //! Variable d'énumération.
              /*! Détails. */
              enumVar;

    //! Un constructeur.
    /*!
        Une description plus élaborée du constructeur.
    */
    QTstyle_Test();

    //! Un destructeur.
    /*!
        Une description plus élaborée du destructeur.
    */
    ~QTstyle_Test();

    //! Un membre normal prenant deux arguments et renvoyant une valeur entière.
    /*!
        \param a un argument entier.
        \param s un pointeur de caractère constant.
        \return Les résultats du test
        \sa QTstyle_Test(), ~QTstyle_Test(), testMeToo() et publicVar()
    */
    int testMe(int a,const char *s);

    //! Un membre virtuel pur.
    /*!
        \sa testMe()
        \param c1 le premier argument.
        \param c2 le deuxième argument.
    */
    virtual void testMeToo(char c1,char c2) = 0;

    //! Une variable publique.
    /*!
        Détails.
    */
    int publicVar;

    //! Une variable de fonction.
    /*!
        Détails.
    */
    int (*handler)(int a,int b);
};

Cliquez ici pour accéder à la documentation HTML correspondante générée par Doxygen.

Les descriptions brèves sont incluses dans la vue d'ensemble des membres d'une classe, d'un espace de noms ou d'un fichier et sont imprimées en utilisant une petite police italique (cette description peut être masquée en définissant BRIEF_MEMBER_DESC sur NO dans le fichier de configuration). Par défaut, les descriptions brèves deviennent la première phrase des descriptions détaillées (mais cela peut être modifié en définissant la balise REPEAT_BRIEF sur NO). Les descriptions brèves et détaillées sont toutes deux facultatives pour le style Qt.

Par défaut, un bloc de documentation de style Javadoc se comporte de la même manière qu'un bloc de documentation de style Qt. Cependant, cela n'est pas conforme à la spécification Javadoc, où la première phrase du bloc de documentation est automatiquement traitée comme une brève description. Pour activer ce comportement, vous devez définir JAVADOC_AUTOBRIEF sur YES dans le fichier de configuration. Si vous activez cette option et que vous souhaitez mettre un point au milieu d'une phrase sans la terminer, vous devez mettre une barre oblique inverse et un espace après. Voici un exemple :

/** Brève description (par exemple, \ en utilisant seulement quelques mots). Les détails suivent. */

Voici le même morceau de code que celui présenté ci-dessus, cette fois documenté en utilisant le style Javadoc et JAVADOC_AUTOBRIEF défini sur OUI :

/**
* Une classe de test. Une description de classe plus élaborée.
*/

class Javadoc_Test
{
  public:

    /**
      * Une énumération.
      * Description d'énumération plus détaillée.
      */

    enum TEnum {
      TVal1, /**< valeur d'énumération TVal1. */
      TVal2, /**< valeur d'énumération TVal2. */
      TVal3 /**< valeur d'énumération TVal3. */
    }
    *enumPtr, /**< pointeur d'énumération. Détails. */
    enumVar; /**< variable enum. Détails. */

      /**
        * Un constructeur.
        * Une description plus élaborée du constructeur.
        */
      Javadoc_Test();

      /**
        * Un destructeur.
        * Une description plus élaborée du destructeur.
        */
      ~Javadoc_Test();

      /**
        * un membre normal prenant deux arguments et renvoyant une valeur entière.
        * @param a un argument entier.
        * @param s un pointeur de caractère constant.
        * @see Javadoc_Test()
        * @see ~Javadoc_Test()
        * @see testMeToo()
        * @see publicVar()
        * @return Les résultats du test
        */
        int testMe(int a,const char *s);

      /**
        * Un membre virtuel pur.
        * @see testMe()
        * @param c1 le premier argument.
        * @param c2 le deuxième argument.
        */
        virtual void testMeToo(char c1,char c2) = 0;

      /**
        * une variable publique.
        * Détails.
        */
        int publicVar;

      /**
        * une variable de fonction.
        * Détails.
        */
        int (*handler)(int a,int b);
};

Cliquez ici pour accéder à la documentation HTML correspondante générée par Doxygen.

De même, si l'on souhaite que la première phrase d'un bloc de documentation de style Qt soit automatiquement traitée comme une brève description, on peut définir QT_AUTOBRIEF sur YES dans le fichier de configuration.

Documentation à d'autres endroits

Dans les exemples de la section précédente, les blocs de commentaires étaient toujours situés devant la déclaration ou la définition d'un fichier, d'une classe ou d'un espace de noms, ou devant ou après l'un de ses membres. Bien que cela soit souvent confortable, il peut parfois y avoir des raisons de placer la documentation ailleurs. Pour documenter un fichier, c'est même nécessaire car il n'existe pas de "devant un fichier".

Doxygen vous permet de placer vos blocs de documentation pratiquement n'importe où (l'exception est à l'intérieur du corps d'une fonction ou à l'intérieur d'un bloc de commentaires de style C normal).

Le prix à payer pour ne pas placer le bloc de documentation directement avant (ou après) un élément est la nécessité de placer une commande structurelle à l'intérieur du bloc de documentation, ce qui conduit à une duplication des informations. En pratique, vous devriez éviter d'utiliser des commandes structurelles, sauf si d'autres exigences vous y obligent.

Les commandes structurelles (comme toutes les autres commandes) commencent par une barre oblique inverse (\), ou un signe arobase (@) si vous préférez le style Javadoc, suivi d'un nom de commande et d'un ou plusieurs paramètres. Par exemple, si vous souhaitez documenter la classe Test dans l'exemple ci-dessus, vous auriez également pu placer le bloc de documentation suivant quelque part dans l'entrée lue par Doxygen :

/*! \class Test
\brief Une classe de test.

Une description de classe plus détaillée.
*/

Ici, la commande spéciale \class est utilisée pour indiquer que le bloc de commentaires contient la documentation de la classe Test. D'autres commandes structurelles sont :

• \struct pour documenter une structure C.
• \union pour documenter une union.
• \enum pour documenter un type d'énumération.
• \fn pour documenter une fonction.
• \var pour documenter une variable ou un typedef ou une valeur d'énumération.
• \def pour documenter un #define.
• \typedef pour documenter une définition de type.
• \file pour documenter un fichier.
• \namespace pour documenter un espace de noms.
• \package pour documenter un package Java.
• \interface pour documenter une interface IDL.

Voir la section Commandes spéciales pour des informations détaillées sur ces commandes et bien d'autres.

Pour documenter un membre d'une classe C++, vous devez également documenter la classe elle-même. Il en va de même pour les espaces de noms. Pour documenter une fonction C globale, un typedef, une énumération ou une définition de préprocesseur, vous devez d'abord documenter le fichier qui le contient (il s'agit généralement d'un fichier d'en-tête, car ce fichier contient les informations exportées vers d'autres fichiers sources).

Voici un exemple d'en-tête C nommé structcmd.h qui est documenté à l'aide de commandes structurelles :

/*! \file structcmd.h
      \brief Un fichier documenté.

      Détails.
*/

/*! \def MAX(a,b)
      \brief Une macro qui renvoie le maximum de \a a et \a b.

      Détails.
*/

/*! \var typedef unsigned int UINT32
      \brief Une définition de type pour a .

      Détails.
*/

/*! \var int errno
      \brief Contient le dernier code d'erreur.

      \warning Non thread-safe !
*/

/*! \fn int open(const char *pathname,int flags)
      \brief Ouvre un descripteur de fichier.

      \param pathname Le nom du descripteur.
      \param flags Drapeaux d'ouverture.
*/

/*! \fn int close(int fd)
      \brief Ferme le descripteur de fichier \a fd.
      \param fd Le descripteur à fermer.
*/

/*! \fn size_t write(int fd,const char *buf, size_t count)
      \brief Écrit \a count octets de \a buf dans le descripteur de fichier \a fd.
      \param fd Le descripteur dans lequel écrire.
      \param buf Le tampon de données dans lequel écrire.
      \param count Le nombre d'octets à écrire.
*/

/*! \fn int read(int fd,char *buf,size_t count)
      \brief Lit les octets d'un descripteur de fichier.
      \param fd Le descripteur à partir duquel lire.
      \param buf Le tampon dans lequel lire.
      \param count Le nombre d'octets à lire.
*/

#define MAX(a,b) (((a)>(b))?(a):(b))
typedef unsigned int UINT32;
int errno;
int open(const char *,int);
int close(int);
size_t write(int,const char *, size_t);
int read(int,char *,size_t);

Cliquez Cliquez ici pour accéder à la documentation HTML correspondante générée par Doxygen.

Comme chaque bloc de commentaires dans l'exemple ci-dessus contient une commande structurelle, tous les blocs de commentaires peuvent être déplacés vers un autre emplacement ou fichier d'entrée (le fichier source par exemple), sans affecter la documentation générée. L'inconvénient de cette approche est que les prototypes sont dupliqués, donc toutes les modifications doivent être effectuées deux fois ! Pour cette raison, vous devez d'abord déterminer si cela est vraiment nécessaire et éviter les commandes structurelles si possible. Je reçois souvent des exemples qui contiennent la commande \fn dans des blocs de commentaires placés devant une fonction. Il s'agit clairement d'un cas où la commande \fn est redondante et ne peut qu'entraîner des problèmes.

Lorsque vous placez un bloc de commentaires dans un fichier avec l'une des extensions suivantes .dox, .txt, .doc, .md ou .markdown ou lorsque l'extension correspond à md au moyen de EXTENSION_MAPPING, Doxygen masquera ce fichier de la liste des fichiers.

Si vous avez un fichier que Doxygen ne peut pas analyser mais que vous souhaitez quand même documenter, vous pouvez l'afficher tel quel en utilisant \verbinclude, par exemple

/*! \file myscript.sh
* Regardez ce joli script :
* \verbinclude myscript.sh
*/

Assurez-vous que le script soit explicitement répertorié dans INPUT ou que FILE_PATTERNS inclut l'extension .sh et que le script peut être trouvé dans le chemin défini via EXAMPLE_PATH.

Blocs de commentaires en Python

Pour Python, il existe une méthode standard de documentation du code à l'aide de chaînes dites de documentation ("""). Ces chaînes sont stockées dans __doc__ et peuvent être récupérées au moment de l'exécution. Doxygen extraira ces commentaires et supposera qu'ils doivent être représentés de manière préformatée.

"""@package docstring
Documentation pour ce module.

Plus de détails.
"""

def func() :
  """Documentation pour une fonction.

  Plus de détails.
  """
  pass

class PyClass :
  """Documentation pour une classe.

    Plus de détails.
  """

  def __init__(self) :
    """Le constructeur."""
    self._memVar = 0 ;

  def PyMethod(self) :
    """Documentation pour une méthode."""
    pass

Cliquez ici pour accéder à la documentation HTML correspondante générée par Doxygen.

Il existe également une autre façon de documenter le code Python en utilisant des commentaires commençant par "##" ou "##<". Ces types de blocs de commentaires sont plus en phase avec la façon dont fonctionnent les blocs de documentation pour les autres langages pris en charge par Doxygen et cela permet également l'utilisation de commandes spéciales.

Voici le même exemple, mais maintenant en utilisant des commentaires de style Doxygen :

## @package pyexample
# Documentation pour ce module.
#
# Plus de détails.

## Documentation pour une fonction.
#
# Plus de détails.
def func():
  pass

## Documentation pour une classe.
#
# Plus de détails.
class PyClass:

    ## Le constructeur.
    def __init__(self):
      self._memVar = 0;

    ## Documentation pour une méthode.
    # @param self Le pointeur d'objet.
    def PyMethod(self):
      pass

    ## Une variable de classe.
    classVar = 0;

    ## @var _memVar
    # une variable membre

Cliquez ici pour accéder à la documentation HTML correspondante générée par Doxygen.

Comme Python ressemble plus à Java qu'à C ou C++, vous devez définir OPTIMIZE_OUTPUT_JAVA sur YES dans le fichier de configuration.

Blocs de commentaires en VHDL

Pour VHDL, un commentaire commence normalement par "--". Doxygen extrait les commentaires commençant par "--!". Il n'existe que deux types de blocs de commentaires en VHDL ; un commentaire "--!" sur une ligne représentant une brève description et un commentaire "--!" sur plusieurs lignes (où le préfixe "--!" est répété pour chaque ligne) représentant une description détaillée.

Les commentaires sont toujours situés devant l'élément qui est documenté, à une exception près : pour les ports, le commentaire peut également être après l'élément et est alors traité comme une brève description du port.

Voici un exemple de fichier VHDL avec des commentaires Doxygen :

-------------------------------------------------------
--! @file
--! @brief 2:1 Mux utilisant with-select
-------------------------------------------------------

--! Utiliser la bibliothèque standard
library ieee;
--! Utiliser les éléments logiques
  use ieee.std_logic_1164.all;

--! Brève description de l'entité Mux

--! Description détaillée de cet
--! élément de conception de mux.
entity mux_using_with est
    port (
      din_0 : in std_logic; --! Mux first input
      din_1 : in std_logic; --! Mux Second input
      sel : in std_logic; --! Select input
      mux_out : out std_logic --! Mux output
    );
end entity;

--! @brief Définition de l'architecture du MUX
--! @details Plus de détails sur cet élément mux.
architecture behavior of mux_using_with is
begin
    with (sel) select
    mux_out <= din_0 when '0',
                din_1 when others;
end architecture;

Cliquez ici pour accéder à la documentation HTML correspondante générée par Doxygen.

Depuis VHDL 2008, il est également possible d'utiliser les commentaires de style *. Doxygen traitera les commentaires de style * ... / comme des commentaires simples et les commentaires de style *! ... / comme des commentaires spéciaux à analyser par Doxygen.

Pour obtenir une sortie correcte, vous devez définir OPTIMIZE_OUTPUT_VHDL sur YES dans le fichier de configuration. Cela affectera également un certain nombre d'autres paramètres. Lorsqu'ils n'étaient pas déjà définis correctement, Doxygen produira un avertissement indiquant quels paramètres ont été annulés.

Blocs de commentaires en Fortran

Lorsque vous utilisez Doxygen pour le code Fortran, vous devez définir OPTIMIZE_FOR_FORTRAN sur YES.

L'analyseur essaie de deviner si le code source est un code Fortran au format fixe ou au format libre. Cela n'est pas toujours correct. Si ce n'est pas le cas, il faut utiliser EXTENSION_MAPPING pour corriger cela. En définissant EXTENSION_MAPPING = f=FortranFixed f90=FortranFree, les fichiers avec l'extension f sont interprétés comme du code Fortran au format fixe et les fichiers avec l'extension f90 sont interprétés comme du code Fortran au format libre.

Pour Fortran, "!>" ou "!<" démarre un commentaire et "!!" ou "!>" peut être utilisé pour continuer un commentaire d'une ligne dans un commentaire multiligne.

Voici un exemple de sous-routine Fortran documentée :

!> Construire la matrice de restriction pour la méthode d'agrégation
!!.
!! @param aggr informations sur les agrégats
!! @todo Gérer les cas spéciaux
subroutine intrestbuild(A,aggr,Restrict,A_ghost)
  implicit none
  Type(SpMtx), intent(in) :: A !< our fine level matrix
  Type(Aggrs), intent(in) :: aggr
  Type(SpMtx), intent(out) :: Restrict !< Our restriction matrix
  !...
end subroutine

Vous pouvez également utiliser des commentaires dans un code au format fixe :

C> Function comment
C> another line of comment
      function a(i)
C> input parameter
        integer i
      end function A

Anatomie d'un bloc de commentaires

La section précédente s'est concentrée sur la façon de faire connaître les commentaires de votre code à Doxygen, elle a expliqué la différence entre une description brève et une description détaillée, et l'utilisation de commandes structurelles.

Dans cette section, nous examinons le contenu du bloc de commentaires lui-même.

Doxygen prend en charge différents styles de formatage de vos commentaires.

La forme la plus simple consiste à utiliser du texte brut. Cela apparaîtra tel quel dans la sortie et est idéal pour une description courte.

Pour des descriptions plus longues, vous aurez souvent besoin d'une structure supplémentaire, comme un bloc de texte textuel, une liste ou un tableau simple. Pour cela, Doxygen prend en charge la syntaxe Markdown, y compris des parties de l'extension Markdown Extra.

Markdown est conçu pour être très facile à lire et à écrire. Son formatage est inspiré du courrier en texte brut. Markdown fonctionne parfaitement pour un formatage simple et générique, comme une page d'introduction pour votre projet. Doxygen prend également en charge la lecture directe des fichiers Markdown. Pour plus de détails, consultez le chapitre Prise en charge de Markdown.

Pour un formatage spécifique au langage de programmation, Doxygen dispose de deux formes de balisage supplémentaire en plus du formatage Markdown.

1. Balisage de type Javadoc. Voir Commandes spéciales pour un aperçu complet de toutes les commandes prises en charge par Doxygen.
2. Balisage XML tel que spécifié dans la norme C#. Voir Commandes XML pour les commandes XML prises en charge par Doxygen.

Si cela ne suffit toujours pas, Doxygen prend également en charge un sous-ensemble du langage de balisage HTML.