web-dev-qa-db-fra.com

Comment intégrer des exemples avec Doxygen?

J'ai documenté toutes mes classes et maintenant je veux intégrer un exemple d'utilisation de ces classes. Comment je fais ça?

documentationdoxygen
37
Tobi Weißhaar

Vous pouvez placer un exemple de code source dans un chemin spécial défini dans la configuration doxygen sous EXAMPLE_PATH, puis insérez des exemples avec le @example tag.

Doxygen générera alors une page supplémentaire contenant la source de l'exemple. Il établira également un lien vers celui-ci à partir de la documentation de la classe contenant l'exemple de balise.

Si vous souhaitez utiliser de petits extraits de code, vous pouvez également les insérer avec @code ... @endcode

La documentation pour cela est ici: documentation doxygen ?

34
Loebl

Une autre méthode consiste à utiliser le \snippet commande.

  • Dans votre fichier d'en-tête, écrivez quelque chose comme:
\section ex1 Example
\snippet path_to_test_class/TestClass.cpp TestClass example
\section ex2 Expected output
\snippet path_to_test_class/TestClass.cpp TestClass expected output
  • Dans le fichier TestClass.cpp, ayez quelque chose comme:
 //! [OptimizeSpeedOnTrackTest example]
 Class c;
 const double res = c.do_something();
 //! [OptimizeSpeedOnTrackTest example]
 //! [OptimizeSpeedOnTrackTest expected output]
 ASSERT_DOUBLE_EQ(5,res);
 //! [OptimizeSpeedOnTrackTest expected output]

path_to_test_class doit être dans votre EXAMPLE_PATH.

Cela vous donne les éléments suivants:

  • Vos exemples ne sont pas seulement là pour la documentation: ils fournissent également une couverture de test
  • Votre testeur (et votre compilateur) vous donne l'assurance que vos exemples compilent et fonctionnent réellement
  • Il s'intègre assez bien dans un flux de travail TDD
18
Deimos

  1. ajouter un moyen de doxyfile EXAMPLE_PATH = dir_example \

  2. peut connecter tous les exemples dans le même fichier comme example_list.h et l'inclure dans doxyfile INPUT = example_list.h \

(langue - russe) http://www.scale-tech.ru/SimBookmaker/doc/html/examples__list_8h_source.html et http://www.scale-tech.ru/ SimBookmaker/doc/html/examples.html

1
Denis

J'ai eu quelques erreurs en utilisant @example pour inclure l'exemple de fichier dans la documentation. C'est la solution de contournement que j'ai utilisée.

Endroit examplefile.cs dans un dossier/projet spécifiquement pour un exemple de code. Placez ce dossier dans la liste Doxygen EXCLUDE (Expert-> Input-> EXCLUDE dans l'interface utilisateur Doxygen GUI) et dans le EXAMPLE_PATH (Expert-> Input-> EXAMPLE_PATH dans l'interface utilisateur de Doxygen GUI)

Placez ce bloc de code quelque part dans un fichier documenté (je le mets dans le fichier auquel l'exemple est destiné.)

/** @example examplefile.cs
 * A description of the example file, causes the example file to show up in 
 * Examples */

Cela provoque l'affichage du fichier sous Exemples dans le menu Doxygen, mais pas en tant que classe/fichier dans votre projet.

Documentez ensuite votre classe/fonction:

/** @brief MyClass does something
 * @details I have something more long winded to say about it.  See example 
 * in examplefile.cs: @include examplefile.cs */

Cela provoque l'impression du fichier d'exemple dans son intégralité dans la documentation de MyClass.

1
Denise Skidmore