Reprendre son propre code nous amène à nous poser parfois... souvent, des questions sur tel ou tel choix... alors reprendre le code d'autre(s) programmeur(s) est encore une autre histoire.
Cette phrase d'introduction amène à dire l'impératif de documenter son code.
Au delà des commentaires basiques qui se trouve dans les fichiers, Doxygen permet d'ajouter des mots clés afin de récupérer des information et d'en créer un ensemble html ou un fichier Latex.
Dans un premier temps, j'aborde la documentation du code : liste des classes, des modifications apportées, graphes de hiérarchie de classe (cf. mon article sur l'utilisation de graphviz avec Doxygen) mais Doxygen permet également de créer une documentation utilisateur.
Pour générer l'arbre (colonne gauche) de sommaire, il faut cocher la case GENERATE_TREEVIEW dans la section HTML de l'onget Expert de la configuration de doxygen
Exemple de fichier pour définir la documentation du code, notamment la mainpage :
nota : j'ai remplacé les références aux codes réels par ... ou des termes génériques!
/*!
\file documentation.h
\brief Récupitulatif des modifications et introduction de la documentation
\mainpage Cette documentation permet de détailler le programme du ....
\author bcag2
\tableofcontents
\section Introduction
Il liste les fichiers .h, .cpp et .rc du projet ainsi que les classes qu'ils contiennent. (soit quelques xxK lignes de code!)\n
Il est généré automatiquement avec Doxygen à partir des fichiers sources qui contiennent dans l'en-tête des mots clés.
\section outils Outils de développement
Le compilateur utilisé est ..., le projet utilisant la bibliothèque ... associée
Le logiciel pour réaliser la documentation est \b doxygen et graphviz\n
tutoriels et doc pour doxygen ici : \n
- http://axiomcafe.fr/tutoriel-documenter-un-code-avec-doxygen
- http://franckh.developpez.com/tutoriels/outils/doxygen/ \n
et liste des commandes en "markdown": \n
- http://www.stack.nl/~dimitri/doxygen/manual/commands.html \n
et pour graphviz :\n
- http://cyberzoide.developpez.com/graphviz
- http://www.graphviz.org/Documentation.php
J'utilise aussi git 2.8.0.windows.1 et tortoisegit pour la gestion du code et des révisions encodage des caractères en ANSI (nécessaire pour fonctionner avec ...)
\section description Description du projet
Ce projet est composé de plusieurs projet BCC++, à savoir :
depot\depot.ide c'est le projet principal pour créer la version en production
depot\depot_virtuel.ide équivalent du projet principal mais sans appareil ni hard, ce projet permet de vérifier la logique
\section conventions Conventions
Les \b modifications ds les fichiers sont en grande partie tracées par le mot DONE (effectué, par opposition à TODO, à faire). De plus, ce mot est en gras dans le fichier html généré par Doxygen grâce au \\b placé devant. A chaque modification dans le code, ce fichier est modifier pour historiser les modif. \n Sur le haut (en ligne 63), on ajoute la \\date suivi de la date du jour, suivi éventuellement de la branche git sur laquelle on travaille.\n
Un retour à la ligne est imposé par \\n \n
\\e ou \\em pour mettre en \em italique, \\c pour précéder un mot de \c code, \\code ... \\endcode pour un bloc de code et un tiret ou \\li en début de ligne génère des "puces"
Si un commit git intervient (version testée en simu ok, à tester/mettre en production), on ajoute la version. Je ne mets plus la valeur du commit ce qui permet de commiter ce fichier avec! En revanche, pour s'y retrouver, il est important d'ajouter la version au commit avec "git tag v1.x.x" qu'on retrouve facilement ensuite avec "git log --decorate"
\section todo A faire
On utilise le mot \\todo ou TODO :
- déverminer?? Erreur Exception
- remplacer les \c char * par \c string (difficile car de nombreuses fonctions utilisent du \c char *... \c string->c_str() ) !\n
http://cpp.developpez.com/faq/cpp/?page = strings#STRINGS_type_chaine !!!!! include <string> et include <string.h> ce n'est pas la même chose !!! \n
- faire en sorte de n'avoir plus qu'une fonction \c fctRedondante... correctement testé !n
- utiliser des \c namespace ??
- YAGNI (http://fr.wikipedia.org/wiki/YAGNI) il me semble intéressant de l'appliquer !!
- Augmenter la précision à 2 chiffres après la virgule pour la consigne et les mesures ...? à priori fait le 18/07/2014
- Ajouter la possibilité d'importer une formule TFCalc
\section pages Pages associées annuelles
Dans l'onglet <A HREF="pages.html">Pages associées</A>, vous trouverez la liste des modifications au fur et à mesure des années
*/
/*! \page 2016 modifications de codes de 2016
\date 2016-avril-07
Correction bug suite modifications dans \c nomClasse::nomMethode ... --> v2.0.26
\date 2016-avril-06
Correction de fichier.cpp \c nomClasse::nomMethode
Les modifications des années antérieures sont dans des fichiers séparées nommés documentation_2015.h, documentation_2014.h */