Doxygen, Graphviz, Mscgen, Dia, Eclox et documentation superbe

Publié par Charly le 21/06/2015 (2789 lectures)

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... Confus(e)

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

0 Commentaire(s) ~ Articles du même auteur