Questions fréquemment posées

Table des matières

Comment obtenir des informations sur la page d'index en HTML ?

Vous devez utiliser la commande \mainpage dans un bloc de commentaires comme ceci :

/*! \mainpage Ma page d'index personnelle
 *
 * \section intro_sec Introduction
 *
 * Ceci est l'introduction.
 *
 * \section install_sec Installation
 *
 * \subsection step1 Étape 1 : Ouverture de la boîte
 *
 * etc...
 */

A l'aide, certains/tous les membres de ma classe/fichier/espace de noms ne sont pas documentés ?

Vérifiez les points suivants :

  1. Votre classe/fichier/espace de noms est-il documenté ? Si ce n'est pas le cas, il ne sera pas extrait des sources à moins que EXTRACT_ALL ne soit défini sur YES dans le fichier de configuration.
  2. Les membres sont-ils privés ? Si c'est le cas, vous devez définir EXTRACT_PRIVATE sur YES pour les faire apparaître dans la documentation.
  3. Existe-t-il une macro de fonction dans votre classe qui ne se termine pas par un point-virgule (par exemple MY_MACRO()) ? Si tel est le cas, vous devez demander au préprocesseur de Doxygen de le supprimer.

Cela se résume généralement aux paramètres suivants dans le fichier de configuration :

ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
PREDEFINED = MY_MACRO()=

Veuillez lire la section de prétraitement du manuel pour plus d'informations.

Lorsque je règle EXTRACT_ALL sur NO, aucune de mes fonctions n'est affichée dans la documentation.

Pour que les fonctions globales, les variables, les énumérations, les définitions de type et les définitions soient documentées, vous devez documenter le fichier dans lequel ces commandes se trouvent à l'aide d'un bloc de commentaires contenant une commande \file (ou @file.

Vous pouvez également placer tous les membres d'un groupe (ou d'une rubrique) à l'aide de la commande \ingroup, puis documenter le groupe à l'aide d'un bloc de commentaires contenant la commande \defgroup.

Pour les fonctions membres ou les fonctions qui font partie d'un espace de noms, vous devez documenter soit la classe, soit l'espace de noms.

Mon fichier avec une extension personnalisée n'est pas (correctement) analysé (plus).

Doxygen analyse uniquement les fichiers spécifiés en entrée (via la balise [INPUT]./configuration-html.md#input)) et qui correspondent à une extension spécifiée (mentionnée dans FILE_PATTERNS). La liste des fichiers est ensuite réduite en excluant les fichiers répertoriés comme EXCLUDE ou les fichiers qui correspondent aux modèles définis par EXCLUDE_PATTERNS.

Dans le passé, Doxygen analysait tous les fichiers avec une extension inconnue comme des fichiers C, ce qui pouvait conduire à des résultats indésirables. Depuis la version 1.8.8, Doxygen exige que vous spécifiiez un mappage qui indique pour une certaine extension de fichier, quel analyseur utiliser. Ce mappage est spécifié à l'aide de la balise EXTENSION_MAPPING. Si aucun mappage n'est spécifié, le contenu du fichier sera ignoré.

Comment puis-je faire en sorte que Doxygen ignore un fragment de code ?

La nouvelle méthode, la plus simple, consiste à ajouter un bloc de commentaires avec une commande \cond au début et un bloc de commentaires avec une commande [\endcond] (./commandes-speciales#endcond) à la fin du morceau de code à ignorer. Cela doit bien sûr se trouver dans le même fichier.

Mais vous pouvez également utiliser le préprocesseur de Doxygen pour cela. Si vous mettez :

#ifndef DOXYGEN_SHOULD_SKIP_THIS

/* code qui doit être ignoré par Doxygen */

#endif /* DOXYGEN_SHOULD_SKIP_THIS */

autour des blocs qui doivent être cachés et que vous mettez :

PREDEFINED = DOXYGEN_SHOULD_SKIP_THIS

dans le fichier de configuration, alors tous les blocs doivent être ignorés par Doxygen tant que ENABLE_PREPROCESSING est défini sur YES.

Comment puis-je modifier ce qui se trouve après le #include dans la documentation de la classe ?

Dans la plupart des cas, vous pouvez utiliser STRIP_FROM_INC_PATH pour supprimer une partie définie par l'utilisateur d'un chemin.

Vous pouvez également documenter votre classe comme suit

/*! \class MyClassName include.h path/include.h
 *
 * Docs pour MyClassName
 */

Pour que Doxygen place

#include <path/include.h>

dans la documentation de la classe MyClassName, quel que soit le nom du fichier d'en-tête réel dans lequel la définition de MyClassName est contenue.

Si vous souhaitez que Doxygen indique que le fichier d'inclusion doit être inclus en utilisant des guillemets au lieu de crochets angulaires, vous devez saisir :

/*! \class MyClassName myhdr.h "path/myhdr.h"
*
* Documents pour MyClassName
*/

Comment puis-je utiliser des fichiers de balises en combinaison avec du HTML compressé ?

Si vous souhaitez faire référence à partir d'un fichier HTML compressé a.chm vers un autre fichier HTML compressé appelé b.chm, le lien dans a.chm doit avoir le format suivant :

<a href="mk:@MSITStore:b.chm::/file.html">

Malheureusement, cela ne fonctionne que si les deux fichiers HTML compressés se trouvent dans le même répertoire.

En conséquence, vous devez renommer les fichiers index.chm générés pour tous les projets en quelque chose d'unique et placer tous les fichiers .chm dans un seul répertoire.

Supposons que vous ayez un projet a faisant référence à un projet b en utilisant le fichier de balises b.tag, vous pouvez alors renommer l'index.chm du projet a en a.chm et l'index.chm du projet b en b.chm. Dans le fichier de configuration du projet a*, vous écrivez :

TAGFILES = b.tag=mk:@MSITStore:b.chm::

Je n'aime pas l'index rapide qui est placé au-dessus de chaque page HTML, que dois-je faire ?

Vous pouvez désactiver l'index en définissant DISABLE_INDEX sur YES. Vous pouvez ensuite insérer votre propre fichier d'en-tête en écrivant votre propre en-tête et en l'alimentant dans HTML_HEADER.

La sortie HTML globale est différente, alors que je voulais seulement utiliser mon propre fichier d'en-tête HTML.

Vous avez probablement oublié d'inclure la feuille de style doxygen.css générée par Doxygen. Vous pouvez inclure cela en mettant :

<LINK HREF="doxygen.css" REL="stylesheet" TYPE="text/css">

dans la section HEAD de la page HTML.

Pourquoi Doxygen utilise Qt ?

Dans le passé (avant la version 1.9.2), Doxygen utilisait une partie de Qt 2.x pour diverses classes utilitaires. Celles-ci ont été remplacées entre-temps par des classes de conteneur STL.

L'interface graphique appelée Doxywizard est basée sur une version moderne de Qt. Doxygen lui-même peut également être utilisé sans l'interface graphique.

Comment puis-je exclure tous les répertoires de test de mon arborescence de répertoires ?

Insérez simplement un modèle d'exclusion comme celui-ci dans le fichier de configuration :

EXCLUDE_PATTERNS = */test/*

Doxygen génère automatiquement un lien vers la classe MyClass quelque part dans le texte en cours d'exécution. Comment puis-je empêcher cela à un certain endroit ?

Mettez un % devant le nom de la classe. Comme ceci : %MyClass. Doxygen supprimera alors le % et conservera le mot non lié.

Mon langage de programmation préféré est X. Puis-je toujours utiliser Doxygen ?

Non, pas en tant que tel ; Doxygen doit comprendre la structure de ce qu'il lit. Si cela ne vous dérange pas de passer un peu de temps dessus, il existe plusieurs options :

  • Si la grammaire de X est proche de C ou C++, il n'est probablement pas trop difficile de modifier un peu src/scanner.l pour que le langage soit pris en charge. Cela est fait pour tous les autres langages directement pris en charge par Doxygen (c'est-à-dire Java, IDL, C#, PHP).
  • Si la grammaire de X est quelque peu différente, vous pouvez écrire un filtre d'entrée qui traduit X en quelque chose d'assez similaire à C/C++ pour que Doxygen le comprenne (cette approche est adoptée pour VB, Object Pascal et JavaScript, voir https://www.doxygen.org/helpers.html).
  • Si la grammaire est complètement différente, on pourrait écrire un analyseur pour X et écrire un backend qui produit un arbre syntaxique similaire à celui réalisé par src/scanner.l (et aussi par src/tagreader.cpp lors de la lecture des fichiers de balises).

Au secours ! J'obtiens le message crytique « dépassement de capacité du tampon d'entrée, impossible d'agrandir le tampon car le scanner utilise REJECT »

Cette erreur se produit lorsque le scanner lexical de Doxygen a une règle qui correspond à plus de 256 000 caractères d'entrée en une seule fois. J'ai vu cela se produire sur un fichier généré très volumineux (> 256 000 lignes), où le préprocesseur intégré l'a converti en un fichier vide (avec > 256 000 de nouvelles lignes). Un autre cas où cela peut se produire est si vous avez des lignes dans votre code avec plus de 256 000 caractères.

Si vous avez rencontré un tel cas et que vous souhaitez que je le corrige, vous devez m'envoyer un fragment de code qui déclenche le message. Pour contourner le problème, insérez des sauts de ligne dans votre fichier, divisez-le en parties plus petites ou excluez-le de l'entrée à l'aide de EXCLUDE.

Une autre façon de contourner ce problème est d'utiliser la commande cmake avec l'option :

-Denlarge_lex_buffers=<size>

où <size> est la nouvelle taille du tampon d'entrée (YY_BUF_SIZE) et de lecture (YY_READ_BUF_SIZE). Si cette option n'est pas donnée, la valeur par défaut de 262144 (soit 256 Ko) sera utilisée.

Lorsque j'exécute make dans le répertoire latex, j'obtiens "TeX capacity exceeded". Et maintenant ?

Vous pouvez éditer le fichier texmf.cfg pour augmenter les valeurs par défaut des différents tampons, puis exécuter "texconfig init".

Pourquoi les dépendances via les classes STL ne sont-elles pas affichées dans les graphiques à points ?

Doxygen ne connaît pas les classes STL, à moins que l'option BUILTIN_STL_SUPPORT ne soit activée.

J'ai des problèmes pour faire fonctionner le moteur de recherche avec PHP5 et/ou Windows

Veuillez lire ceci pour savoir où chercher.

Puis-je configurer Doxygen à partir de la ligne de commande ?

Pas via les options de ligne de commande, mais Doxygen peut lire à partir de stdin, vous pouvez donc y envoyer des éléments. Voici un exemple de remplacement d'une option dans un fichier de configuration à partir de la ligne de commande (en supposant un environnement de type UNIX) :

( cat Doxyfile ; echo "PROJECT_NUMBER=1.0" ) | doxygen -

Pour la ligne de commande Windows, ce qui suit ferait la même chose :

( type Doxyfile & echo PROJECT_NUMBER=1.0 ) | doxygen.exe -

Pour Windows Powershell (vérifié avec la version 5.1), ce qui suit ferait la même chose :

&{ type Doxyfile ; echo "PROJECT_NUMBER=1.0" } | doxygen -

Si plusieurs options avec le même nom sont spécifiées, Doxygen utilisera la dernière. Pour ajouter à une option existante, vous pouvez utiliser l'opérateur +=.

Comment Doxygen a-t-il obtenu son nom ?

Doxygen a obtenu son nom en jouant avec les mots documentation et generator.

documentation -> docs -> dox
generator -> gen

A l'époque, je m'intéressais à lex et yacc, où beaucoup de choses commencent par "yy", donc le "y" s'est glissé et a rendu les choses prononçables (la prononciation correcte est Docs-ee-gen, donc avec un long "e").

Quelle était la raison du développement de Doxygen ?

J'ai déjà écrit un widget GUI basé sur la bibliothèque Qt (il est toujours disponible sur https://sourceforge.net/projects/qdbttabular/ mais n'a pas été mis à jour depuis 2002). Qt avait généré une documentation bien faite (en utilisant un outil interne qu'ils ne voulaient pas publier) et j'ai écrit des documents similaires à la main. C'était un cauchemar à maintenir, donc je voulais un outil similaire. J'ai regardé Doc++ mais ce n'était tout simplement pas assez bon (il ne prenait pas en charge les signaux et les slots et n'avait pas l'apparence et la convivialité de Qt que j'avais appris à aimer), alors j'ai commencé à écrire mon propre outil...

Comment éviter les sorties entrelacées

Lors de la redirection de toutes les sorties de la console de Doxygen, c'est-à-dire les messages et les avertissements, celles-ci peuvent être entrelacées ou dans un ordre inattendu. La raison technique en est que la sortie stdout peut être mise en mémoire tampon. Il est possible de surmonter cela au moyen du -b de Doxygen, comme par exemple doxygen -b > out.txt 2>&1. Notez cependant que cela peut prendre un peu plus de temps.