1 Doxygen

2 Doxygen : qu’est-ce que c’est ? Code C++, Java,... ● Un générateur de documentation – pour C + +, mais aussi C, Java, Fortran,... – Il fonctionne sur la plupart des systèmes Unix, y compris Mac OS X, ainsi que sur Windows ● Plusieurs formats de sortie: – HTML, mais aussi Latex, PDF, PS, XML, Man pages ● Un outil pour l'écriture de logiciels de documents de référence. – La documentation est écrite dans le code, et il est donc relativement facile de la tenir à jour. – Doxygen peut traverser la documentation de référence et le code, de sorte que le lecteur d'un document peut facilement consulter le code actuel.

3 Règles de base ● Tout la documentation est générée à partir des commentaires dans le code suivants quelques-unes règles simple ● Le commentaire qui devrait apparaître dans la documentation générée doit commencer par – /// – D'autres possibilités sont les suivantes: / ** ou / *! ou / /! ● L'emplacement par défaut pour les commentaires est avant la structure que nous voulons documenter (classe, fonction membre,...) – Le commentaire peut également être placé à un autre endroit, dans ce cas il doit être précédé par un mot-clé correspondant à la structure documentée ● Par exemple : ● /// \class MyClass ● /// \file MyFile

4 Qu'est qu´on va documenter ● Les champs qui doivent être documentés peuvent être définis en fixant les options appropriées dans le fichier de configuration, Doxyfile – Doxygen peut alors générer un avertissement lorsque la documentation est manquante ● Dans nos cours nous allons documenter : – Les fichiers – Les classes – Les fonctions (y compris les fonctions de membre de la classe) – Les données membres de la classe

5 Comment documenter... #include /// \file fileName.ext /// \brief A brief description of the file. /// /// A more complete description of the file. /// Probably over several lines. /// \brief A brief description of myClass. /// /// A more complete description of myClass. /// Probably over several lines. class myClass {... un Fichier... une Classe

6 Comment documenter... /// \brief A brief description of myFunction. /// /// A more complete description of myFunction. /// Probably on several lines. /// \param anArgument A brief description of anArgument. /// \return A brief description of what myFunction returns std::string myFunction (std::string anArgument); /// \brief A brief description of myVariable. /// /// A more complete description of myVariable. /// Probably over several lines. std::string myVariable;... une Fonction... une Variable

7 Plus de conseils... ● Utilisation de HTML tags ● Plus de mots-clés ● Listes /// Example /// Status myFunction(); /// ChangeLog /// \author Leroi Arthur /// A list of characteristics: /// - an item /// -# numbered 1 /// -# numbered 2 /// - another

8... Plus de conseils ● Liens ● Page principale (elle peut être placée dans un fichier séparé, mainpage.h) /// \see Classname /// \see #AnotherMethod /// \see AnotherClass#AnotherMethod /// \mainpage The package Test /// /// \section intro Introduction /// … /// \section install Installation … /// \subsection step_1 First step … /// \subsection step_2 Second step … /// … /// The file ChangeLog

9 Doxyfile ● Le fichier de configuration – Comprend les diverses options pour la génération de documentation – Peut être généré comme un patron (toutes les options prennent leurs valeurs par défaut et ils sont précédés d'un commentaire explicatif) $> Doxygen-g configFile # # Project related configuration options # # The PROJECT_NAME tag is a single word (or a sequence of words surrounded # by quotes) that should identify the project. PROJECT_NAME = "Shapes" # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) # base path where the generated documentation will be put. # If a relative path is entered, it will be relative to the location # where doxygen was started. If left blank the current directory will be used. OUTPUT_DIRECTORY = doc...