Commandes personnalisées

Table des matières

Doxygen fournit un grand nombre de commandes spéciales, commandes XML et commandes HTML. qui peuvent être utilisées pour améliorer ou structurer la documentation à l'intérieur d'un bloc de commentaires. Si, pour une raison quelconque, vous avez besoin de définir de nouvelles commandes, vous pouvez le faire au moyen d'une définition d'alias.

La définition d'un alias doit être spécifiée dans le fichier de configuration à l'aide de la balise de configuration ALIASES.

Alias ​​simples

La forme la plus simple d'un alias est une simple substitution de la forme

nom=valeur

Par exemple, définir l'alias suivant :

ALIASES += sideeffect="\par Effets secondaires :^^"

vous permettra de placer la commande \sideeffect (ou @sideeffect) dans la documentation, ce qui donnera lieu à un paragraphe défini par l'utilisateur avec le titre Effets secondaires :.

Notez que vous ne pouvez pas mettre de \n dans la partie valeur d'un alias pour insérer des sauts de ligne (dans la sortie résultante). Vous pouvez mettre ^^ dans la partie valeur d'un alias pour insérer un saut de ligne comme si un saut de ligne physique était dans le fichier d'origine.

Notez que lorsque vous avez besoin d'un { ou } ou , (ou d'un séparateur non par défaut) littéral dans la partie valeur d'un alias, vous devez l'échapper au moyen d'une barre oblique inverse (\), cela peut entraîner des conflits avec les commandes \{ et \} pour celles-ci, il est conseillé d'utiliser la version @{ et @} ou d'utiliser un double échappement (\\{ et \\})

Notez également que vous pouvez redéfinir les commandes spéciales existantes si vous le souhaitez.

Certaines commandes, telles que \xrefitem, sont conçues pour être utilisées en combinaison avec des alias.

Alias ​​avec arguments

Les alias peuvent également avoir un ou plusieurs arguments. Dans la définition de l'alias, vous devez alors spécifier le nombre d'arguments entre accolades. Dans la partie valeur de la définition, vous pouvez placer des marqueurs \x, où 'x' représente le numéro d'argument commençant par 1.

Voici un exemple de définition d'alias avec un seul argument :

ALIASES += l{1}="\ref \1"

Dans un bloc de commentaires, vous pouvez l'utiliser comme suit :

/** Voir \l{SomeClass} pour plus d'informations. */

ce qui équivaudrait à écrire :

/** Voir \ref SomeClass pour plus d'informations. */

Notez que vous pouvez surcharger un alias par une version avec plusieurs arguments, par exemple :

ALIASES += l{1}="\ref \1"
ALIASES += l{2}="\ref \1 \"\2\""

Notez que les guillemets à l'intérieur de la définition d'alias doivent être échappés avec une barre oblique inverse.

Avec ces définitions d'alias, nous pouvons écrire :

/** Voir \l{SomeClass,Some Text} pour plus d'informations. */

à l'intérieur du bloc de commentaires et il s'étendra à

/** Voir \ref SomeClass "Some Text" pour plus d'informations. */

où la commande avec un seul argument fonctionnerait toujours comme indiqué précédemment.

Les alias peuvent également être exprimés en termes d'autres alias, par exemple une nouvelle commande \reminder peut être exprimée comme un \xrefitem via une commande \xreflist intermédiaire comme suit :

ALIASES += xreflist{3}="\xrefitem \1 \"\2\" \"\3\" "
ALIASES += reminder="\xreflist{reminders,Reminder,Reminders}"

Notez que si pour les alias avec plus d'un argument une virgule est utilisée comme séparateur, si vous voulez mettre une virgule à l'intérieur de la commande, vous devrez l'échapper avec une barre oblique inverse, c'est-à-dire :

\l{SomeClass,Some text\, avec une virgule échappée}

étant donné la définition d'alias de \l dans l'exemple ci-dessus.

Par défaut, le séparateur pour les arguments dans un alias est une virgule. Cependant, pour les arguments avec beaucoup de virgules, tels que les modèles de définitions de fonctions, échapper chaque virgule peut être fastidieux. Pour résoudre ce problème, on peut spécifier un séparateur différent, directement après le nombre de paramètres, par exemple pour utiliser un point-virgule comme séparateur, on peut définir la commande comme suit :

ALIASES += xreflist{3;}="\xrefitem \1 \"\2\" \"\3\" "
ALIASES += reminder="\xreflist{reminders;Reminder;Reminders}"

Notez que les séparateurs à plusieurs caractères sont également autorisés, c'est-à-dire que le même exemple peut être écrit en utilisant des symboles à double barre verticale comme séparateur :

ALIASES += xreflist{3||}="\xrefitem \1 \"\2\" \"\3\" "
ALIASES += reminder="\xreflist{reminders||Reminder||Reminders}"

Les caractères suivants sont autorisés pour créer des séparateurs :

!#$%&,.?|;:'+=~`/

Notez que pour chaque commande et chaque nombre de paramètres, on peut utiliser un séparateur différent. Il n'est cependant pas recommandé de sélectionner un séparateur différent pour la même commande, car cela peut entraîner une ambiguïté quant à la définition de commande à utiliser. Doxygen résout cette ambiguïté en choisissant la commande qui correspond au plus grand nombre de paramètres. Considérez l'exemple suivant, plutôt artificiel :

ALIASES += v{2+}="Choisir 2 : '\1' et '\2'"
ALIASES += v{3;}="Choisir 3 : '\1', '\2' et '\3'"

Ensuite

- \v{Un+Deux}
- \v{Un;Deux;Trois}
- \v{Un+Deux;Trois;Quatre}

Produira :

  • Choisir 2 : 'Un' et 'Deux'
  • Choisir 3 : 'Un', 'Deux' et 'Trois'
  • Choisir 3 : 'Un+Deux', 'Trois' et 'Quatre'

Pour la dernière commande, les deux définitions de v correspondent, mais celle avec 3 paramètres est sélectionnée car elle correspond à plus de paramètres.

Imbrication de commandes personnalisées

Vous pouvez utiliser des commandes comme arguments d'alias, y compris des commandes définies à l'aide d'alias.

À titre d'exemple, considérons les définitions d'alias suivantes :

ALIASES += Bold{1}="<b>\1</b>"
ALIASES += Emph{1}="<em>\1</em>"

À l'intérieur d'un bloc de commentaires, vous pouvez désormais utiliser :

/** Ceci est un fragment de texte \Bold{bold \Emph{and} Emphaized}. */

qui s'étendra à

/** Ceci est un fragment de texte <b>bold <em>and</em> Emphaized</b>. */