Comment intégrer des exemples avec Doxygen ?

Question

J'ai documenté toutes mes classes et je veux maintenant intégrer un exemple d'utilisation de ces classes. Comment dois-je m'y prendre ?

Answer 1

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

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

Si vous souhaitez utiliser de petits extraits de code, vous pouvez également les insérer à l'aide de la commande @code ... @endcode

La documentation à ce sujet se trouve ici : documentation doxygen ?

Answer 2

Une autre façon de procéder est d'utiliser l'option \snippet commandement.

• 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 programme d'exécution de tests (et votre compilateur) vous donne l'assurance que vos exemples se compilent et s'exécutent réellement.
• Il s'intègre très bien dans un flux de travail TDD.

Answer 3

J'ai rencontré des erreurs en utilisant @example pour inclure le fichier d'exemple dans la documentation. Voici la solution de rechange que j'ai utilisée.

Lieu examplefile.cs dans un dossier/projet spécifique pour le code d'exemple. Placez ce dossier dans la base de données Doxygen EXCLUDE (Expert->Input->EXCLUDEdans l'interface graphique de Doxygen) et dans la liste de l EXAMPLE_PATH (Expert->Input->EXAMPLE_PATH dans l'interface graphique de Doxygen)

Placez ce bloc de code quelque part dans un fichier documenté (je l'ai mis dans le fichier de l'exemple).

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

Cela fait apparaître le fichier sous la rubrique Exemples dans le menu Doxygen, mais pas en tant que classe/fichier dans votre projet.

Ensuite, documentez 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 permet d'imprimer le fichier d'exemple dans son intégralité dans la documentation de MyClass.

Answer 4

1. ajouter un moyen de faire un doxyfile EXAMPLE_PATH = dir_example \

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

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