Articles

Documenter avec Doxygen

Présentation de Doxygen

Documenter son travail est INDISPENSABLE pour plusieurs raisons.

Lorsqu'on oeuvre sur un projet, on garde un assez bon souvenir de ce qu'on écrit sur une échelle de temps relativement courte et ensuite, on oublie. Et si on écrit un code complexe, quelques jours peuvent être suffisants pour ne plus savoir pourquoi on avait écrit ceci ou cela. Il est donc impératif de commenter le code que l'on écrit.

Autre raison, moins évidente à priori : c'est en rédigeant la documentation de son code qu'on se rend parfois compte de ses failles ou de ses limites. Bref, d'une approche faisant appel à un raisonnement manquant de clarté. Documenter progressivement son code permet donc de prendre un peu recul sur ce qu'on fait et de se reposer les bonnes questions.

Pour documenter le code, en langage C, on utilise communément les séquences /* ... */ pour commentaire sur plusieurs lignes et // pour un commentaire valide jusqu'à la fin de la ligne en cours.

Ces commentaires sont utiles pour le programmeur qui reprend le programme plusieurs mois après ou en cours de programmation pour bien explicité les détails un peu pointus ou les portions de code. Il faut savoir rester synthétique dans ces commentaires.

Si le projet comporte de nombreux fichiers, de multiples définitions de fonctions, de macros, de structures ou d'énumérations, sa reprise ultérieure risque rapidement de devenir un cauchemar. C'est là qu'entre en jeu Doxygen.

Doxygen est un programme qui génère la documentation sous forme html d'un projet dont les fichiers ont été commentés en utilisant des balises compréhensible par Doxygen. Le rapport généré permet d'avoir une vision claire des différentes fonctions, définitions, macros, énumérations ... et de permettre leur réutilisation sans avoir à se plonger dans le code. Et si l'objectif est de reprendre un projet pour le faire évoluer, le rapport généré par Doxygen permettra de se familiariser plus rapidement avec l'existant.

Exemple de documentation d'une fonction en langage C avec des balises Doxygen :

/*!
 * \brief Choix du mode Entrée ou Sortie pour une broche.
 *
 * L'exemple ci-dessous montre comment mettre la broche PC3 (PORTC3) en sortie.
 * \code
 IO_setMode(PORTC, PORTC3, OUTPUT_MODE);
 * \endcode
 *
 * \param[in,out]	pPORTreg : pointeur vers le port ciblé.
 * \param[in]	uPin : numéro de bit ciblé sur le port.
 * \param[in]	eMode : mode choisi.
 */
void IO_setMode( volatile uint8_t * pPORTreg, uint8_t uPin, IO_MODE_t eMode )
{
	// Le registre DDRx se trouve un octet en dessous du registre du port PORTx.
	pPORTreg = pPORTreg - 1;
	switch(eMode)
	{
	case OUTPUT_MODE:
		*pPORTreg = *pPORTreg | (1 << uPin);
		break;
	case INPUT_MODE:
		*pPORTreg = *pPORTreg & ( 0xFF & (0 << uPin) );
		break;
	}
}

L'onglet suivant propose une vidéo (un peu indigeste pour le moment) montrant son utilisation dans Atmel Studio.

Note : l'installation de base d'Atmel Studio ne possède pas l'outil Doxygen. Il s'agit d'un addon téléchargeable dans Atmel Gallery (menu Tools \(\rightarrow\)Extension Manager... dans Atmel Studio ; chercher l'extension Doxygen et l'installer).

Doxygen sous Atmel Studio en vidéo

Cette vidéo montre comment procéder pour documenter un programme avec des balises Doxygen et générer ensuite la documentation correspondante.

Lien vers la documentation générée dans cette vidéo : Documentation PremierProgramme.

{jcomments on}