Activité : Documentation du code

Documentation du code

Doxygen

Doxygen est un système de documentation pour C, C++, Java, Python, Php et autres langages. Il permet de générer la documentation de vos développements :

  • à partir des commentaires insérés dans le code source
  • à défaut de commentaires, à partir de la structure du code lui même. La documentation générée sera dans ce cas minimale.

La documentation peut être produite dans des formats variés tels que du HTML, du Latex, du RTF ou du XML.

Doxygen est un logiciel libre, publié sous licence GPL V2.0.

Lire : doc.ubuntu-fr.org/doxygen

Installation

Ubuntu :

$ sudo apt-get install doxygen doxygen-gui doxygen-doc

Pour les graphiques :

$ sudo apt-get install graphviz

Utilisation

Pour lancer l’interface graphique de Doxygen, ouvrez un terminal et entrez la commande suivante :

doxywizard

L’onglet wizard vous permet :

  • de créer votre projet
  • de sélectionner le dossier contenant les sources ou celui accueillant votre documentation
  • de sélectionner le format de sortie : HTML avec ou sans frames, Latex, RTF, pages man, XML, PDF, Postscript.
  • de générer des diagrammes

L’onglet Expert vous permet d’accéder aux options avancées.

Il ne vous reste alors plus qu’à cliquer sur Run pour obtenir le résultat.

Exemple de configuration

Remarques :

  • Sélectionner le Français pour OUTPUT_LANGUAGE
  • Le format HTML est adapté à la navigation et le format PDF est indispensable pour imprimer et avoir l’ensemble de la documentation dans un seul fichier. Le format RTF sera utile pour y faire des copier/coller pour votre dossier.

N’oubliez pas d’enregistrer votre configuration dans un fichier Doxyfile.

Remarque : il est intéressant de générer aussi les diagrammes de classes. Pour cela, veillez à sélectionner les options suivantes :

  • Dans Build :
  • Dans Source Browser :

Tutoriel

Lire :

Exemples

Commentaire pour une classe :

/**
 * \file busi2c.h
 * 
 * \class BusI2C
 * 
 * \brief Gestion du bus I2C pour les circuits LTC2309 et BH1750
 * 
 * \details Classe singleton + ressource critique protégée par un mutex
 * 
 * \author Thierry VAIRA
 * 
 * \version 0.9
 * 
 * \date Lundi 9 mai 2016
 * 
 */

class BusI2C
{
    ... 
};

Commentaire pour une méthode :

/**
 * \brief    Acquérir la valeur numérique d'une entrée analogique du LTC2309
 * \details  Méthode statique permettant de lire le LTC2309 (CAN 12 bits)
 * \param    pin         Numéro du canal 
 * \return   Un \e int représentant la valeur brute de la tension du canal
 */
int BusI2C::analogRawRead(int pin)
{ 
    ...  
}

Il est aussi possible d’obtenir des diagrammes UML :

Vous avez aussi la possibilité de créer des pages de documentation.

Par exemple une page principale :

/*! \mainpage Page principale du projet XXX
 *
 * \section section_intro Introduction
 *
 *
 * Bla bla ....
 *
 * \section section_tdm Table des matières
 * - \ref page_install 
 * - \ref page_about
 * - \ref page_licence
 *
 */

/*! \page page_install Installation
 *
 * \todo rédiger le manuel d'installation
 *
 */

/*! \page page_about A propos
 * \author \a Toto <toto@nowhere.com>
 * \version 1.0
 * \date \b 2016
 */

/*! \page page_licence Licence GPL
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 *
 */

Plugin Qt Creator

Il existe un plugin Doxygen pour Qt Creator qui permet d’intégrer dans l’EDI des fonctionnalités de documentation.

Wiki : http://dev.kofee.org/projects/qtcreator-doxygen/wiki

Remarque : Le plugin est fourni sous forme binaire jusqu’à la version 3.1 de Qt Creator. Pour les versions supérieures, il vous faudra le recompiler à partir des sources.

Pour la version Qt Creator 2.4.1 (64 bits) : qtcreator-doxygen-0.3.5-qtcreator-2.4.1-linux-x86_64.zip

Les plugins de Qt Creator sont installés dans /usr/lib/x86_64-linux-gnu/qtcreator/plugins/(pour une Ubuntu 12.04), donc :

$ sudo unzip qtcreator-doxygen-0.3.5-qtcreator-2.4.1-linux-x86_64.zip -d /usr/lib/x86_64-linux-gnu/qtcreator/plugins/

Il faut relancer Qt Creator.

Vous obtenez un nouveau sous-menu dans le menu Outils :

Utilisation :

  • “Create Doxygen Documentation” : crée les en-têtes de documentation pour la ligne courante
  • “Document whole file” : crée les en-têtes de documentation pour l’ensemble du fichier ouvert
  • “Document whole project” : crée les en-têtes de documentation pour l’ensemble du projet actif
  • “Build Doxygen Documentation” : fabrique la documentation (équivalent à Run dans doxywizard) du projet actif
  • “Edit Doxyfile” : vous permet d’éditer votre fichier de configuration Doxyfile avec doxywizard

D’autre part, vous aurez accès à la complétion pour les commandes Doxygen à partir de @ ou \ :

QML

Lien : github.com/agateau/doxyqml

Retour au sommaire

© 2019 Thierry Vaira