White Cat lighting board

White Cat Lighting Board Documentation

Outils pour utilisateurs

Outils du site


documentation_doxygen

Documentation automatique avec Doxygen

Pour tout les développeurs du projet Whitecat, il a été question avec George Khaznadar de développer automatiquement une documentation de l'API. L'outil choisit s'est porter sur Doxygen qui génère une documentation automatiquement pour permettre de s'y retrouver plus facilement dans les diverses fonctions et sources du chat.

Cette pratique nécessite néanmoins de la part de tous les développeurs contributeurs de commenter leur code afin que les commentaires puissent être reconnu par Doxygen. Ce bref tutoriel répertorie différentes manières de commenter son code, n'hésiter pas à le compléter ou le corriger en cas d'erreur.

Pour ajouter des information destinée à Doxygen il faut créer des balises.

- 1 /*! En C++ au début des infos transmise à Doxygen, /** en C (utiliser de préférence la syntax /*!) .

- 2 * avant chaque nouvelle information et pour un retour à la ligne

- 3 Une ou plusieurs balise java doc: ex * \brief (pour ajouter une description)

- 4 */ pour fermer les commentaires

la balise * \brief ajoute une description

la balise * \fn indique le nom de la fonction et sa description

la balise * \param est à ajouter pour chacun des paramètres avec son type, son nom et une description

la balise * \return permet de donner une description de la valeur retourner

En tête de Fichier.

Ruis-Serge a développer un en tête normalisé. Il serait bien de le rajouter au début de chaque fichier en vérifiant les informations du commentaire Doxygen. J'ai modifier les information de licence et de copyright pour être cohérent avec le dépot gitHub.

/*-------------------------------------------------------------------------------------------------------------
                                 |
          CWWWWWWWW              | Copyright (C) 2013  Christoph Guillermet
       WWWWWWWWWWWWWWW           | 
     WWWWWWWWWWWWWWWWWWW         | This file is part of White Cat.
    WWWWWWWWWWWWWWWWWCWWWW       | 
   WWWWWWWWWWWWWWWWW tWWWWW      | White Cat is free software: you can redistribute it and/or modify
  WWWW   WWWWWWWWWW  tWWWWWW     | it under the terms of the GNU General License as published by
 WWWWWt              tWWWWWWa    | the Free Software Foundation, either version 2 of the License, or
 WWWWWW               WWWWWWW    | (at your option) any later version.
WWWWWWWW              WWWWWWW    | 
WWWWWWWW               WWWWWWW   | White Cat is distributed in the hope that it will be useful,
WWWWWWW               WWWWWWWW   | but WITHOUT ANY WARRANTY; without even the implied warranty of
WWWWWWW      CWWW    W WWWWWWW   | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
WWWWWWW            aW  WWWWWWW   | GNU Lesser General Public License for more details.
WWWWWWWW           C  WWWWWWWW   | 
 WWWWWWWW            CWWWWWWW    | You should have received a copy of the GNU General Public License
 WWWWWWWWW          WWWWWWWWW    | along with White Cat.  If not, see <http://www.gnu.org/licenses/>. 
  WWWWWWWWWWC    CWWWWWWWWWW     |   
   WWWWWWWWWWWWWWWWWWWWWWWW      | 
    WWWWWWWWWWWWWWWWWWWWWW       |    
      WWWWWWWWWWWWWWWWWWa        |     
        WWWWWWWWWWWWWWW          |     
           WWWWWWWWt             |
                                 |
---------------------------------------------------------------------------------------------------------------*/
/**

 \file {nom du fichier.extension}
 \brief {description courte} 
 \author {liste des auteurs}
 \version {numero de version du fichier}
 \date {date description}
 
 White Cat {- categorie} {- sous categorie {- sous categorie}}
 Description détaillée
 
 **/
 

Fonctions et variables

Avant chaque déclaration de fonction indiqué une description en commentaire.

/**
* \brief read an audio file from a particular time
* \param const char* file complet path of the file. must be an audio file(mp3, wave,aiff)
* \param long startTime start of the audio file in millisecond
* \return the number of the file in the playlist -1 if an error
*
*/
int play(const char* file, long startTime)
{
//fonction play
}

Avant chaque déclaration de variable une brève description

/** nombre de players audio */
int nbPlayer;

Un exemple serait peut être plus parlant.

Tout les commentaire précéder de // ne sont pas des commentaires destiner à la documentation par doxygen mais seulement à une meilleur compréhension du code.

En C :

//pour chaque fichier coder en C (.c ou.cpp)
//au début du fichier
/*-------------------------------------------------------------------------------------------------------------
                                 |
          CWWWWWWWW              | Copyright (C) 2013  Christoph Guillermet
       WWWWWWWWWWWWWWW           | 
     WWWWWWWWWWWWWWWWWWW         | This file is part of White Cat.
    WWWWWWWWWWWWWWWWWCWWWW       | 
   WWWWWWWWWWWWWWWWW tWWWWW      | White Cat is free software: you can redistribute it and/or modify
  WWWW   WWWWWWWWWW  tWWWWWW     | it under the terms of the GNU General License as published by
 WWWWWt              tWWWWWWa    | the Free Software Foundation, either version 2 of the License, or
 WWWWWW               WWWWWWW    | (at your option) any later version.
WWWWWWWW              WWWWWWW    | 
WWWWWWWW               WWWWWWW   | White Cat is distributed in the hope that it will be useful,
WWWWWWW               WWWWWWWW   | but WITHOUT ANY WARRANTY; without even the implied warranty of
WWWWWWW      CWWW    W WWWWWWW   | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
WWWWWWW            aW  WWWWWWW   | GNU Lesser General Public License for more details.
WWWWWWWW           C  WWWWWWWW   | 
 WWWWWWWW            CWWWWWWW    | You should have received a copy of the GNU General Public License
 WWWWWWWWW          WWWWWWWWW    | along with White Cat.  If not, see <http://www.gnu.org/licenses/>. 
  WWWWWWWWWWC    CWWWWWWWWWW     |   
   WWWWWWWWWWWWWWWWWWWWWWWW      | 
    WWWWWWWWWWWWWWWWWWWWWW       |    
      WWWWWWWWWWWWWWWWWWa        |     
        WWWWWWWWWWWWWWW          |     
           WWWWWWWWt             |
                                 |
---------------------------------------------------------------------------------------------------------------*/

/** 
* \file audioplayer.cpp
* \brief Whitecat 0.8.5 modification des audio players en intégrant la librairie Juce. 
* \author Christophe Guillermait modified by Anton Langhoff
* \version 0.2
* \date 23/01/2014
*
* 
*/

# include audioplayer.h

//déclaration de la première fonction, meme chose pour toutes les fonction
/**
* \fn int play(const char* file, long startTime)
* \brief permet de lire un fichier audio depuis un moment donner
* \param const char* file chemin du fichier complet. doit être un fichier audio(mp3, wave,aiff)
* \param long startTime départ de la lecture du fichier en milliseconde
* \return le numéro du fichier dans la playlist ou -1 si il y a eu une erreur de lecture
*
*/
int play(const char* file, long startTime)
{
//fonction play
}

En C++ en début de tout fichier.h ::

//pour un fichier en c++ commenter le code avec Doxygen uniquement dans le fichier.h
// mais ajouter quand même les lignes suivante au début de chaque fichier y compris les //fichier .cpp pour les
infos relative au fichier lui même.
/*-------------------------------------------------------------------------------------------------------------
                                 |
          CWWWWWWWW              | Copyright (C) 2013  Christoph Guillermet
       WWWWWWWWWWWWWWW           | 
     WWWWWWWWWWWWWWWWWWW         | This file is part of White Cat.
    WWWWWWWWWWWWWWWWWCWWWW       | 
   WWWWWWWWWWWWWWWWW tWWWWW      | White Cat is free software: you can redistribute it and/or modify
  WWWW   WWWWWWWWWW  tWWWWWW     | it under the terms of the GNU Lesser General License as published by
 WWWWWt              tWWWWWWa    | the Free Software Foundation, either version 2 of the License, or
 WWWWWW               WWWWWWW    | (at your option) any later version.
WWWWWWWW              WWWWWWW    | 
WWWWWWWW               WWWWWWW   | White Cat is distributed in the hope that it will be useful,
WWWWWWW               WWWWWWWW   | but WITHOUT ANY WARRANTY; without even the implied warranty of
WWWWWWW      CWWW    W WWWWWWW   | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
WWWWWWW            aW  WWWWWWW   | GNU Lesser General Public License for more details.
WWWWWWWW           C  WWWWWWWW   | 
 WWWWWWWW            CWWWWWWW    | You should have received a copy of the GNU General Public License
 WWWWWWWWW          WWWWWWWWW    | along with White Cat.  If not, see <http://www.gnu.org/licenses/>. 
  WWWWWWWWWWC    CWWWWWWWWWW     |   
   WWWWWWWWWWWWWWWWWWWWWWWW      | 
    WWWWWWWWWWWWWWWWWWWWWW       |    
      WWWWWWWWWWWWWWWWWWa        |     
        WWWWWWWWWWWWWWW          |     
           WWWWWWWWt             |
                                 |
---------------------------------------------------------------------------------------------------------------*/

/*!
* \file audioplayer.h
* \brief Whitecat 0.8.5 modification des audio players en intégrant la librairie Juce. 
* \author Christophe Guillermait modified by Anton Langhoff
* \version 0.2
* \date 23/01/2014
*
*/

//permet de declarer une nouvelle classe
/*! \class AudioPlayer
* \brief crée un player audio multidiffusion
*
*/

class AudioPlayer
{

/*! \brief contructeur d'un player audio multipiste
*  \param nbOut permet de définir le nombres de sortie utilisées par le player, par default le player est stéréo 
*
*/
AudioPlayer(int nbOut=2);

//pareil pour le destructeur
/*! \brief destructeur du player audio multipiste
*
*/
~AudioPlayer() ;

//déclaration de la première fonction

/*!
* \fn int play(const char* file, long startTime)
* \brief permet de lire un fichier audio depuis un moment donner
* \param const char* file chemin du fichier complet. doit être un fichier audio(mp3, wave,aiff)
* \param long startTime départ de la lecture du fichier en milliseconde
* \return le numéro du fichier dans la playlist ou -1 si il y a eu une erreur de lecture
*
*/
void int play(const char* file, long startTime);

protected:
const char* currentFile;

}

Un tuto plus complet est disponible à cette adresse : http://franckh.developpez.com/tutoriels/outils/doxygen/

Notes :

  • Ne commenter jamais les autres lignes du code avec plus de 2 // (ex:////) sinon Doxygen pourrait voir ces commentaires comme une partie de la documentation.
  • Parfois sur les sources de Whitecat, lorsque que le commentaire se trouve avant une fonction, il faut retirer la balise \fn pour que la fonction soit prise en compte dans la documentation. Si le commentaire est avant la fonction, Doxygen saura qu'il s'applique à cette fonction.
  • N'écrivez jamais d'accent ou de caractère spéciaux dans les commentaires, Doxygen est par défaut en UTF-8.
  • Vérifier toujours avec Doxywizard après des modifications qu'elle ont bien été prises en compte et qu'elle sont bien documentés.

Merci à tous.

documentation_doxygen.txt · Dernière modification: 2014/02/25 19:42 par 85.168.92.135