Documentation avec Doxygen + Graphviz + Mscgen + Dia, le tout géré par Eclox
5 outils ! J’ai cru y perdre mes derniers cheveux mais je ne saurais plus m’en passer !
Voici une présentation de ces outils trés complémentaires et comment les installer/utiliser.
Je fais cet article aujourd'hui pour vous éviter les déboires que j'ai eu malgré le tuto de mcuoneclipse
http://mcuoneclipse.com/2012/06/25/5- ... ygen-graphviz-and-mscgen/
Je ne reprends pas certaines choses décrites dedans mais je le complète avec un outil de plus formidable et quelques détails et bugs chronophages.
et...pour me servir de note pour m'y retrouver dans quelques temps...
Doxygen
Doxygen est un outil de documentation qui génère automatiquement une documentation structurée toute belle, toute propre, à partir de l’analyse du code et de quelques balises à utiliser pour documenter le code. on verra plus bas son utilisation.
Code + documentation sont ainsi produits et mis à jour au même endroit : votre projet Code Warrior.
Doxygen sait gérer quelques graphiques très moyens mais sait gérer d’autres outils de graphiques très performants.
Graphviz
 Graphviz, sait faire des diagrammes de flux, bulles et autres mémory map. Le graph est directement codé par ligne de code dans votre projet. Vous ne décrivez que la structure, la mise en page du graph est automatique. 
voir des exemples
Mscgen
Mscgen, ultra simple sait faire des graphiques séquentiels. Le graph est directement codé par ligne de code dans votre projet. Vous ne décrivez que la tructure, la mise en page du graph est automatique.
Eclox
Eclox est un plugin de Eclipse qui intègre Doxygen + Graphviz +mscgen à Eclispe. Il permet entre autre d'avoir votre documentation qui apparait d'une couleur spéciale dans Code Warrior
Dia
Dia est un outil de dessin à l’ergonomie douteuse (presque du niveau de "Paint" de windows...) mais qui sait tout faire, du schéma électrique au schéma hydraulique en passant par un truc bien pratique pour nous : les chronogrammes.
Graphviz et Mscgen sont d'une grande simplicité et surtotu d'une grande productivité avec un graph automatiquement généré et mis en page ; ce n'est pas le cas de Dia qui est plus "manuel" mais ce coté manuel le rend aussi plus ou moins sans limite...
Doxygen sait intégrer à la documentation les images générées par Dia !
Les 6ièmes outils
Doxygen sait intégrer dans la doc toute image issue de n’importe où (capture oscillo, analyseur logique, photo de vacances...). Ainsi tous les outils de documentations peuvent êtres intégrés à votre doc !
Installation des logiciels
Ce que je décris ici est fait sous Code Warrior 10.6
Commencer par installer Doxygen, puis Graphviz puis Mscgen
http://www.stack.nl/~dimitri/doxygen/ or www.doxygen.org
http://www.graphviz.org
http://www.mcternan.me.uk/mscgen/
Puis installer le plugin Eclox pour Eclipse
Pour cela aller dans CodeWarrior help/Installa new software et indiquer le chemin vers Eclox : http://download.gna.org/eclox/update/ (quelle idée !!? Merci Stephane, je chercherais encore comment installer un plugin ! )
Vous pouvez ensuite installer Dia mais il restera indépendant de Eclox. Vous trouverez Dia ici : http://sourceforge.net/projects/dia-installer/
Configuration de Code Warrior et de Doxygen
>>Pour activer les couleurs du code doxygen dans votre code il faut aller dans ls préférences de CW : préférences/C/C++/Editor workspace default -> à régler sur "Doxygen"
>>Tous les paramètres de votre documentation sont ensuite gérés dans un document .doxyfile
Processor expert crée automatiquement un fichier Doxyfile du nom de pex.doxyfile. Il faut impérativement en créer un autre à vous car pex.doxyfile est recréé à chaque compilation, avec bien sur tous vos paramètres qui volent...
En double cliquant sur le .doxyfile Eclipse ouvre un onglet permettant de configurer tous les paramètres depuis Code Warrior. Ca remplace le "DoxyWizard" dont parle la doc de Doxygen.
>>Faire fonctionner Graphviz : Il faut paramétrer le chemin de dot.exe dans le paramètre "DOT_PATH du .doxyfile.
Attention l'editeur de Eclox a un bug pour l'ecriture des chemins, les / ne sont pas dans le bon sens et les chemins ne sont pas noté en relatif !!
Chez moi le chemin de dot.exe est ainis paramétré dans le .doxyfile : "../../../../../../Program Files (x86)/Graphviz2.38/bin"
>>Faire fonctionner l'insertion d'images : Il faut donner le chemin du dossier où se trouvent les images dans le paramètre "Image Path" du .doxyfile
>>Faire fonctionner l'insertion d'images Dia : Il faut donner le chemin du dossier où se trouvent les images (et projets Dia pour plus d'ergonomie) dans le paramètre "DIAFILE_DIRS" du .doxyfile
>>Texte en francais : Si comme moi vous souhaitez intégrer du Francais dans votre documentation il faudra :
Activer dans CW l'UTF-8 pour le format des fichiers
Windows > Preferences > General > Workspace, set "Text file encoding" to "Other : UTF-8
Windows > Preferences > General > Content Types, set UTF-8 as the default encoding for all content types.
Les fichiers doivent être convertis en UTF8 dans notepad++ par ailleurs
Exemples
>>Mscgen
msc
hscale = "2";
a,b,c;
a->b [ label = "ab()" ] ;
b->c [ label = "bc(TRUE)"];
c=>c [ label = "process(1)" ];
c=>c [ label = "process(2)" ];
...;
c=>c [ label = "process(n)" ];
c=>c [ label = "process(END)" ];
a<<=c [ label = "callback()"];
--- [ label = "If more to run", ID="*" ];
a->a [ label = "next()"];
a->c [ label = "ac1()nac2()"];
b<-c [ label = "cb(TRUE)"];
b->b [ label = "stalled(...)"];
a<-b [ label = "ab() = FALSE"];
endmsc
Va donner ceci :
>>Graphviz
dot
digraph Param
{
graph [rankdir = "LR";];
PC[shape=circle];
µC[shape=trapezium];
NAND1[label="NANDflash bloc A"];
NAND2[label="NANDflash bloc A'"];
Usine[label="Valeurs d'usine des n structures écrites en dur";];
EEPROM[label="EEPROM 25LC640";];
PC -> µC ;
µC -> PC [label="Fichier INI";fontsize = 11];
µC -> NAND1 ;
NAND1 -> µC [label="structure de paramètresn Minicore et application (binaire)";fontsize = 11] ;
NAND1 -> NAND2 ;
NAND2 -> NAND1 [label="permutation à chaquen modif de paramètre";fontsize = 11];
µC -> Usine ;
Usine -> µC [label="structures de n paramètres (binaire)";fontsize = 11];
µC -> EEPROM ;
EEPROM -> µC [label="structure de paramètresn propres à la fille (binaire)";fontsize = 11];
subgraph cluster_Core {
label = "Minicore"
style = rounded
color = springgreen4
µC
NAND1
NAND2
Usine
}
subgraph cluster_fille {
label = "Carte fille"
style = rounded
color = red
EEPROM
}
}
enddot
Va donner ceci :
dot
digraph G
{
graph [rankdir = "LR"];
"NANdFlash" [
label = "<f0> Bloc 0 n ...n ...n Logsn ...n ...n (64 pages de n 2112o par page)n ...n ...n Bloc 2045 |
<f1> Bloc 2046 n Paramètres |<f2> Bloc 2047 n Paramètres BIS "
shape = "record"
title= "toto";
];
subgraph Minicore {
rank = same;
"Param2" [
label = "<f0> Page 0 n ...n Texte libre utilisateurn ...n Page 1 |
<f1> Page 2 n ...n Structures des paramètres n de la Minicore ou n liés à l'application n ...n Page 63"
shape = "record"
title= "toto";
];
"Param1" [
label = "<f0> Page 0 n ...n Texte libre utilisateurn ...n Page 1 |
<f1> Page 2 n ...n Structures des paramètres n de la Minicore ou n liés à l'application n ...n Page 63"
shape = "record"
title= "toto";
];
Param1 -> Param2 ;
Param2 -> Param1 [label="permutation à chaquen modif de paramètre"];
}
"NANdFlash":f1 -> "Param1":f0 ;
"NANdFlash":f2 -> "Param2":f0 ;
}
enddot
Va donner ceci :
>>Dia chronogramme
diafile Diagramme1.png "mon graph"
Va donner ceci :
>>Insérer une image
>>insérer du code dans la documentation
* @code Utilisation : status = PCF212X_ConfigClockOut_Et_PeriodeTemperature_RTC(QUATRE_MIN, HIGH_Z) ; @endcode
>>Marquer une tache à faire dans la todolist qui apparait clairement dans la documentation
/*! todo Faire que ca ne plante plus !!!*/
>>Créer une page d'accueil structurée
?>
A placer où on veut dans le code