Dépannage

Problèmes connus

  • Doxygen n'est pas un vrai compilateur, c'est juste un scanner lexical. Cela signifie qu'il ne peut pas détecter les erreurs dans votre code source et qu'il ne le fera pas.
  • Doxygen dispose d'un préprocesseur intégré, mais celui-ci fonctionne légèrement différemment du préprocesseur C. Doxygen suppose qu'un fichier d'en-tête est correctement protégé contre les inclusions multiples et que chaque fichier d'inclusion est autonome (c'est-à-dire qu'il peut être placé en haut d'un fichier source sans provoquer d'erreurs de compilation). Tant que cela est vrai (et c'est une bonne pratique de conception), vous ne devriez pas rencontrer de problèmes.
  • Comme il est inimaginable de tester tous les fragments de code possibles, il est très probable qu'un morceau valide de code C/C++ ne soit pas traité correctement. Si vous trouvez un tel morceau, envoyez-le-moi, afin que je puisse améliorer les capacités d'analyse de Doxygen. Essayez de rendre le morceau de code que vous envoyez aussi petit que possible, pour m'aider à affiner la recherche.
  • Doxygen ne fonctionne pas correctement s'il existe plusieurs classes, structures ou unions portant le même nom dans votre code. Il ne devrait cependant pas planter, il devrait plutôt ignorer toutes les classes portant le même nom sauf une.
  • Certaines commandes ne fonctionnent pas à l'intérieur des arguments d'autres commandes. À l'intérieur d'un lien HTML (c'est-à-dire ...) par exemple, d'autres commandes (y compris d'autres commandes HTML) ne fonctionnent pas ! Les commandes de sectionnement sont une exception importante.
  • Les accolades redondantes peuvent perturber Doxygen dans certains cas. Par exemple :
void f (int);

est correctement analysé comme une déclaration de fonction, mais :

const int (a);

est également considéré comme une déclaration de fonction portant le nom int, car seule la syntaxe est analysée, pas la sémantique. Si les accolades redondantes peuvent être détectées, comme dans :

int *(a[20]);

alors Doxygen supprimera les accolades et analysera correctement le résultat.

  • Tous les noms des fragments de code inclus dans la documentation ne sont pas remplacés par des liens (par exemple lors de l'utilisation de SOURCE_BROWSER = YES) et les liens vers des membres surchargés peuvent pointer vers le mauvais membre. Cela vaut également pour la liste « Référencé par » qui est générée pour chaque fonction.

Cela est dû en partie au fait que l'analyseur de code n'est pas assez intelligent pour le moment. J'essaierai d'améliorer cela à l'avenir. Mais même avec ces améliorations, tout ne peut pas être correctement lié à la documentation correspondante, en raison d'éventuelles ambiguïtés ou d'un manque d'informations sur le contexte dans lequel se trouve le fragment de code.

  • Il n'est pas possible d'insérer une fonction non membre f dans une class A à l'aide de la commande \relates ou **\relatesalso**, si la class A possède déjà un membre avec le nom f et la même liste d'arguments.
  • Il n'existe actuellement qu'un support très limité pour la spécialisation des membres. Cela ne fonctionne que s'il existe également une classe modèle spécialisée.
  • Toutes les commandes spéciales ne sont pas correctement traduites en RTF.
  • La version 1.8.6 de dot (et peut-être aussi les versions antérieures) ne génère pas de fichiers de carte appropriés, ce qui fait que les graphiques générés par Doxygen ne sont pas correctement cliquables.
  • PHP uniquement : Doxygen exige que toutes les instructions PHP (c'est-à-dire le code) soient enveloppées dans des fonctions/méthodes, sinon vous risquez de rencontrer des problèmes d'analyse.

Comment aider

Le développement de Doxygen dépend fortement de votre contribution !

Si vous essayez Doxygen, faites-moi savoir ce que vous en pensez (est-ce que certaines fonctionnalités vous manquent ?). Même si vous décidez de ne pas l'utiliser, dites-moi pourquoi.

Comment signaler un bug

Les bugs sont suivis dans le suivi des problèmes de GitHub. Avant de soumettre un nouveau bug, recherchez d'abord dans la base de données si le même bug a déjà été soumis par d'autres. Si vous pensez avoir trouvé un nouveau bug, veuillez le signaler.

Si vous n'êtes pas sûr qu'il s'agisse d'un bogue, demandez d'abord de l'aide (un abonnement est nécessaire) sur la liste de diffusion des utilisateurs ou sur Stack Overflow en utilisant l'étiquette doxygen.

Si vous n'envoyez qu'une description (vague) d'un bug, vous n'êtes généralement pas très utile et il me faudra beaucoup plus de temps pour comprendre ce que vous voulez dire. Dans le pire des cas, votre rapport de bug peut même être complètement ignoré par moi, alors essayez toujours d'inclure les informations suivantes dans votre rapport de bug :

  • La version de Doxygen que vous utilisez (par exemple 1.5.3, utilisez doxygen --version si vous n'êtes pas sûr ou doxygen --Version pour un peu plus d'informations).
  • Le nom et le numéro de version de votre système d'exploitation (par exemple Ubuntu Linux 18.04 LTS)
  • C'est généralement une bonne idée d'envoyer également le fichier de configuration, mais veuillez utiliser Doxygen avec l'indicateur -s lors de sa génération pour le garder petit (utilisez doxygen -s -u [configName] pour supprimer les commentaires d'un fichier de configuration existant. Il est même préférable d'utiliser l'indicateur -x ou -x_noenv sur le [configName] utilisé pour obtenir les différences entre les paramètres utilisés et les paramètres par défaut de Doxygen, donc doxygen -x [configName]).
  • Le moyen le plus simple (et souvent le seul) pour moi de corriger les bugs est de joindre un petit exemple illustrant le problème que vous avez au rapport de bug, afin que je puisse le reproduire sur ma machine. Veuillez vous assurer que l'exemple est un code source valide (il pourrait potentiellement compiler) et que le problème est vraiment capturé par l'exemple (je reçois souvent des exemples qui ne déclenchent pas le bug réel !). Si vous avez l'intention d'envoyer plus d'un fichier, veuillez compresser ou archiver les fichiers ensemble dans un seul fichier pour un traitement plus facile. Notez que lorsque vous signalez un nouveau bug, vous n'aurez la possibilité d'y joindre un fichier qu'après avoir soumis la description initiale du bug.
  • Avant de soumettre, envisagez également d'exécuter Doxygen avec des indicateurs de débogage, exécutez doxygen -d pour tous les indicateurs. L'option preprocessor peut vous donner des indications sur la façon dont Doxygen comprend vos fichiers d'entrée.

Vous pouvez (et êtes encouragé à) ajouter un correctif pour un bug signalé. Si vous le faites, veuillez utiliser « issue #NUMBER TITLE » comme titre dans le formulaire de demande d'extraction, où « NUMBER » et « TITLE » font référence au problème associé sur GitHub.

Si vous avez des idées sur la façon de corriger les bugs et les limitations existants, veuillez en discuter sur la liste de diffusion des développeurs (abonnement requis). Les correctifs peuvent également être envoyés directement à doxygen@gmail.com si vous préférez ne pas les envoyer via le bug tracker ou la liste de diffusion.

Pour les correctifs, veuillez utiliser « diff -uN » ou inclure les fichiers que vous avez modifiés. Si vous envoyez plusieurs fichiers, veuillez tout compresser ou tout compresser, afin que je n'aie à enregistrer et télécharger qu'un seul fichier.