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.
- 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
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
**/
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;
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/
Merci à tous.