Génération automatique de liens

Table of Contents

La plupart des systèmes de documentation ont des sections spéciales « voir aussi » où des liens vers d'autres éléments de documentation peuvent être insérés. Bien que Doxygen dispose également d'une commande pour démarrer une telle section (voir la section \sa), il vous permet de placer ce type de liens n'importe où dans la documentation. Pour la documentation latex, une référence au numéro de page est écrite à la place d'un lien. De plus, l'index à la fin du document peut être utilisé pour trouver rapidement la documentation d'un membre, d'une classe, d'un espace de noms ou d'un fichier. Pour les pages de manuel, aucune information de référence n'est générée.

Les sections suivantes montrent comment générer des liens vers les différentes entités documentées dans un fichier source.

Liens vers des pages Web et des adresses e-mail

Doxygen remplacera automatiquement toutes les URL et adresses e-mail trouvées dans la documentation par des liens (en HTML). Pour spécifier manuellement le texte du lien, utilisez la balise HTML « a » :

<a href="linkURL">texte du lien</a>

qui sera automatiquement traduit dans d'autres formats de sortie par Doxygen.

Liens vers les classes

Tous les mots de la documentation qui correspondent à une classe documentée et qui contiennent au moins un caractère non minuscule seront automatiquement remplacés par un lien vers la page contenant la documentation de la classe. Si vous souhaitez empêcher qu'un mot correspondant à une classe documentée soit remplacé par un lien, vous devez mettre un % devant le mot. Pour créer un lien vers un symbole tout en minuscules, utilisez \ref.

Liens vers les fichiers

Tous les mots qui contiennent un point (.) qui n'est pas le dernier caractère du mot sont considérés comme des noms de fichiers. Si le mot est effectivement le nom d'un fichier d'entrée documenté, un lien sera automatiquement créé vers la documentation de ce fichier.

Liens vers les fonctions

Des liens vers les fonctions sont créés si l'un des modèles suivants est rencontré :

  1. <<functionName>"("<argument-list>")"
  2. <functionName>"()"
  3. "::"<functionName>
  4. <(className>"::")n<functionName>"("<argument-list>")"
  5. <(className>"::")n<functionName>"("<argument- list>")"<modifiers>
  6. <(className>"::")n<functionName>"()"
  7. (<className>"::")n<functionName>

où n>0.

Remarque 1 :
Les arguments de fonction doivent être spécifiés avec les types corrects, c'est-à-dire fun(const std::string&,bool) ou () pour correspondre à n'importe quel prototype.

Remarque 2 :
Les modificateurs de fonction membre (comme « const » et « volatile ») sont nécessaires pour identifier la cible, c'est-à-dire que « func(int) const » et « func(int) » ciblent des fonctions membres différentes.

Remarque 3 :
Pour la compatibilité Javadoc, un # peut être utilisé à la place d'un :: dans les modèles ci-dessus.

Remarque 4 :
Dans la documentation d'une classe contenant un membre foo, une référence à une variable globale est faite en utilisant « ::foo », tandis que #foo créera un lien vers le membre.

Pour les membres non surchargés, la liste d'arguments peut être omise.

Si une fonction est surchargée et qu'aucune liste d'arguments correspondante n'est spécifiée (c'est-à-dire que le modèle 2 ou 6 est utilisé), un lien sera créé vers la documentation de l'un des membres surchargés.

Pour les fonctions membres, la portée de classe (telle qu'utilisée dans les modèles 4 à 7) peut être omise si :

  1. Le modèle pointe vers un membre documenté qui appartient à la même classe que le bloc de documentation qui contient le modèle.
  2. La classe qui correspond aux blocs de documentation qui contiennent le modèle a une classe de base qui contient un membre documenté qui correspond au modèle.

Liens vers autres membres

Toutes ces entités peuvent être liées de la même manière que celle décrite dans la section précédente. Par souci de clarté, il est conseillé d'utiliser uniquement les modèles 3 et 7 dans ce cas.

Exemple :

 /*! \file autolink.cpp
    Test de la génération automatique de liens.

    Un lien vers un membre de la classe Autolink_Test : Autolink_Test::member,

    Des liens plus spécifiques vers chacun des membres surchargés :
    Autolink_Test::member(int) et Autolink_Test#member(int,int)

    Un lien vers une variable membre protégée de Autolink_Test : Autolink_Test#var,

    Un lien vers le type d'énumération global #GlobEnum.

    Un lien vers la définition #ABS(x).

    Un lien vers le destructeur de la classe Autolink_Test : Autolink_Test::~Autolink_Test,

    Un lien vers le typedef ::B.

    Un lien vers le type d'énumération Autolink_Test::EType

    Un lien vers certaines valeurs d'énumération Autolink_Test::Val1 et ::GVal2
 */

 /*!
    Ce bloc de documentation appartient à la classe Autolink_Test qui peut également être
    liée avec #Autolink_Test.

    Pour créer un lien vers un constructeur : #Autolink_Test() et Autolink_Test().

    Les liens vers le destructeur sont : #~Autolink_Test et ~Autolink_Test().

    Un lien vers un membre de cette classe : member().

    Des liens plus spécifiques vers chacun des membres surchargés :
    member(int) et member(int,int).

    Un lien vers la variable #var.

    Un lien vers le typedef global ::B.

    Un lien vers le type d'énumération global #GlobEnum.

    Un lien vers la définition ABS(x).

    Un lien vers une variable \link #var utilisant un autre texte\endlink comme lien.

    Un lien vers le type d'énumération #EType.

    Un lien vers des valeurs d'enum : \link Autolink_Test::Val1 Val1 \endlink et ::GVal1.

    Et enfin, un lien vers un fichier : autolink.cpp.

    \sa Dans une section voir aussi, n'importe quel mot est vérifié, donc EType,
        Val1, GVal1, ~Autolink_Test et member seront remplacés par des liens en HTML.
 */

 class Autolink_Test
 {
    public:
        Autolink_Test(); //!< constructor
      ~Autolink_Test(); //!< destructor
        void member(int);           /**< Une fonction membre. Détails. */
        void member(int,int);       /**< Une fonction membre surchargée. Détails */

        /** Un type d'énumération. Plus de détails */
        enum EType {
        Val1,                       /**< valeur d'énumération 1 */
        Val2                        /**< valeur d'énumération 2 */
        };

    protected:
    int var;                        /**< Une variable membre */
};

 /*! détails. */
 Autolink_Test::Autolink_Test() { }

 /*! détails. */
 Autolink_Test::~Autolink_Test() { }

 /*! Une variable globale. */
 int globVar;

 /*! Une énumération globale. */
 enum GlobEnum {
        GVal1,                      /*!< valeur d'énumération globale 1 */
        GVal2                       /*!< valeur d'énumération globale 2 */
 };

 /*!
  * Une définition de macro.
  */
 #define ABS(x) (((x)>0)?(x):-(x))

 typedef Autolink_Test B;

 /*! \fn typedef Autolink_Test B
  * Une définition de type.
 */

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

Typedefs

Les typedefs impliquant des classes, des structures et des unions, comme :

typedef struct StructName TypeName

crée un alias pour StructName, afin que des liens soient générés vers StructName, lorsque StructName lui-même ou TypeName est rencontré.

Exemple :

/*! \file restypedef.cpp
 * Un exemple de résolution de typedefs.
 */

/*! \struct CoordStruct
 * Une paire de coordonnées.
 */
struct CoordStruct
{
    /*! La coordonnée x */
    float x;
    /*! La coordonnée y */
    float y;
};

/*! Crée un nom de type pour CoordStruct */
typedef CoordStruct Coord;

/*!
 * Cette fonction renvoie l'addition de \a c1 et \a c2, c'est-à-dire :
 * (c1.x+c2.x,c1.y+c2.y)
 */
Coord add(Coord c1,Coord c2)
{
}

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