:: Enseignements :: Licence :: L3 :: 2012-2013 :: Programmation C ::

Doc my code

But du projet

Vous devez réaliser un programme permettant de générer la documentation technique d'une application à partir de ses sources en C documentées. Le principe, les spécifications et l'objectif de votre programme sont les mêmes que la mythique Javadoc... ou que l'outil doxygen.

Contenu de la documentation

La documentation technique générée prendra la forme d'un site Web dynamique (HTML, CSS, Javascript, etc.), permettant de parcourir aisément les sources documentées (à l'instar de Javadoc), et d'obtenir au minimum les informations suivantes :

l'arborescence des fichiers sources de l'application ;
pour chaque fichier d'entête (fichier.h) associé à un fichier source (fichier.c), la liste des fonctions, variables, structures, macros, etc., qui y sont déclarées ;
pour chaque fonction, la description de son rôle (à quoi la fonction sert, et ce qu'elle renvoie) et de ses paramètres.

La documentation d'une fonction, variable, structure, macro, etc., peut être indifféremment décrite dans le fichier d'entête (fichier.h) et/ou dans le fichier source associé (fichier.c). Votre programme devra considérer cette éventualité.

Voici un extrait de documentation pouvant être générée par votre programme :

Figure 1. Documentation du contenu d'un fichier source voitures.c.

Figure 2. Documentation d'une fonction calculerDistance().

Bien entendu, vous avez toute liberté de modifier l'aspect de la documentation générée, et donc de ne pas obtenir une documentation strictement identique à l'exemple ci-dessus. Veillez toutefois à ce que l'utilisation de votre documentation générée reste simple et logique.
La documentation générée doit être la plus pratique et ergonomique possible. Par exemple, il doit être possible de naviguer dans cette documentation à l'aide de liens hypertextes, permettant notamment d'accéder directement à la description d'une fonction particulière en cliquant sur le nom de celle-ci dans la liste des fonctions du fichier source documenté. Vous pouvez vous inspirer de ce que proposent les documentations générées par les outils Javadoc ou doxygen.

Documentation des sources

La documentation générée est extraite directement des sources de l'application, sur la base de commentaires de documentation écrits par les développeurs directement dans les fichiers sources, et respectant un format spécifique.

Bloc de documentation

Un commentaire est considéré comme un bloc de documentation s'il respecte l'un des deux formats suivants :

/**  ...
     ... documentation ...
 */

///  ...
///  ... documentation ...
///  ...

Remarquez qu'il s'agit de commentaires classiques auxquels sont ajoutés des caractères spécifiques : une étoile (*) supplémentaire, ou trois barres obliques (/) au lieu de deux.

Important : la seule contrainte est qu'un bloc de documentation utilise au moins deux étoiles (*) pour la première ligne, ou trois barres obliques (/) pour chaque ligne ! De plus, les deux formats peuvent être indifféremment utilisés ; l'ensemble des blocs de documentation devront être pris en compte.
Ainsi, l'intégralité des commentaires suivants représentent la documentation de la fonction func :

/*********************************
 **  \fn        int func()      **
     \brief     Une petite fonction qui ne fait pas grand chose...
 ********************************/
//////////////////////////////////  \author Moi
///  \details   Quel bel exemple de fonction inutile !
///             On aurait largement pu s'en passer...
///  \return    0
//////////////////////////////////
int func() {
    return 0;
}

Balises spéciales

Plusieurs balises spéciales permettent de spécifier les informations que l'on décrit sur une fonction ou un fichier source. Voici les principales balises que votre programme devra gérer.

\file : Spécifie le nom du fichier concerné par le bloc de documentation. On peut ainsi ajouter des informations de documentation sur un fichier source, même à partir d'un autre fichier.
```
\file  fichier.c
```
\author : Indique l'auteur de la fonction ou du fichier source.
```
\author  Mathieu Chapelle
```
\version : Indique la version du code.
```
\version  1.0
```
\date : Indique une date associée au bloc de documentation.
```
\date  24 octobre 2012
```
\brief : Donne une courte description du rôle de la fonction ou du fichier source documenté.
```
\brief  Courte description de ma fonction.
```
\details : Donne une description plus détaillée du rôle et du fonctionnement de la fonction (et de ses paramètres) ou du fichier source documenté.
```
\details  Longue description de ma fonction, qui peut s'étaler sur
          plusieurs lignes. Et aussi se faire en plusieurs phrases !
```
\fn : Donne le prototype complet de la fonction documentée.
```
\fn  int main(int argc, char* argv[])
```
\param : Décrit le rôle d'un paramètre de la fonction documentée.
```
\param  argc    nombre d'arguments dans le tableau
```

\return : Décrit le retour de la fonction documentée.

\return  Retourne la somme des éléments du tableau.

\bug : Décrit un potentiel bug.

\bug  L'affichage est incorrect si la tableau est vide.

Dans le cas des balises acceptant une précision sur l'élément décrit (notamment \param), la séparation entre l'élément décrit et la précision se fait à l'aide d'au moins deux espaces ou d'une tabulation.

Il doit être possible d'utiliser plusieurs fois une même balise dans un même bloc de documentation ; leur contenu sera alors regroupé dans la documentation générée. Par exemple, dans le cas d'une fonction ayant plusieurs paramètres, on devra utiliser \param pour chacun de ces paramètres, et ces informations seront regroupées dans un bloc Paramètres dans la documentation générée.

Exemple de code documenté

L'extrait de documentation précédent (Figure 1 et Figure 2) a été obtenu à partir des fichiers sources documentés ainsi :

/**
 * \file      voitures.c
 * \author    Miroslav
 * \version   1.0
 * \date      12 Novembre 2009
 * \brief     Définit les modèles de voiture et leur particularités.
 *
 * Cette classe surcharge les accesseurs standards du module_voiture pour
 * convenir aux spécificités des différents modèles possibles.
 */

... // suite du code

...

/**
 * \fn         float calculerDistance(Point point1, Point point2)
 * \brief      Calcule la distance entre deux points
 * \details    La distance entre les \a point1 et \a point2 est calculée par
 *             l'intermédiaire des coordonnées des points. (cf #Point)
 * \param      point1    Point 1 pour le calcul de distance.
 * \param      point2    Point 2 pour le calcul de distance.
 * \return     Un \e float représentant la distance calculée.
 */
float calculerDistance(Point point1, Point point2);

..

Utilisation de votre programme

Votre programme sera utilisé en ligne de commandes, et génèrera automatiquement la documentation technique dynamique à partir des fichiers sources de l'application. Votre programme devra gérer trois possibilités de passer ces fichiers sources :

L'ensemble des fichiers sources à documenter sont passés en argument :
```
user@pc:~$ docmycode fichier1.c fichier2.c main.c
```
Un chemin vers la racine du projet est passé en argument :
```
user@pc:~$ docmycode /chemin/vers/mon/projet/
```
Le programme est appelé depuis la racine du projet :
```
user@pc:/chemin/vers/mon/projet/$ docmycode
```

Améliorations et extensions

Les fonctionnalités décrites ci-dessus sont le strict minimum que votre programme devra être capable de proposer. Lorsque l'intégralité des consignes décrites ci-dessus seront correctement implémentées par votre programme, vous pourrez lui ajouter des améliorations et extensions. Nous vous proposons ici quelques idées d'extensions ; libre à vous d'en trouver d'autres !

Remarque : Ces améliorations et extensions feront partie intégrante de l'évaluation de votre projet.
Plus vous ajouterez de fonctionnalités, et meilleure sera l'évaluation de votre projet.

Autres balises spéciales

Vous remarquerez que le format spécifique de la documentation est librement inspiré (pompé) des outils très connus que sont Javadoc et doxygen. Nous n'avons listé que quelques unes des balises spéciales gérées par ces outils, mais il en existe beaucoup d'autres.

Vous pouvez piocher parmi l'ensemble des balises spéciales gérées par l'outil doxygen, pour ajouter des balises spéciales gérées par votre programme. Faites un choix judicieux : commencez par implémenter les balises les plus utiles et pertinentes !
Certaines balises sont indicatives ou cosmétiques, et permettent de contrôler l'affichage des informations dans la documentation générée. C'est le cas notamment des balises \a, \c ou encore \e. Ces balises peuvent être très utiles pour améliorer la compréhension d'une documentation ; peut-être serait-il judicieux de les choisir prioritairement...

Détection automatique du prototype des fonctions documentées

Dans les balises spéciales minimales se trouve la balise \fn, qui permet de définir le prototype complet d'une fonction documentée. En extension, et à l'instar du fonctionnement des outils Javadoc et doxygen, vous pouvez améliorer votre programme pour qu'il détecte automatiquement ce prototype, sans qu'il soit nécessaire de l'indiquer par l'utilisation de la balise \fn.
Dans l'exemple ci-dessus documentant la fonction calculerDistance(), le bloc de documentation deviendrait :

...

/**
 * \brief      Calcule la distance entre deux points
 * \details    La distance entre les \a point1 et \a point2 est calculée par
 *             l'intermédiaire des coordonnées des points. (cf #Point)
 * \param      point1    Point 1 pour le calcul de distance.
 * \param      point2    Point 2 pour le calcul de distance.
 * \return     Un \e float représentant la distance calculée.
 */
float calculerDistance(Point point1, Point point2);

..

Notez que le prototype n'est plus décrit par une balise \fn ; le programme détecte automatiquement ce prototype comme étant celui défini juste après la fin du bloc de documentation.

Fichier de configuration

Il peut être intéressant de pouvoir modifier le comportement de votre programme, qu'il s'agisse de la manière dont sont traités les fichiers sources documentés, ou de l'aspect de la documentation générée. Dans les outils tels que Javadoc ou doxygen, ce comportement peut être paramétré à l'aide d'un ou plusieurs fichiers de configuration.
À l'instar de ces outils, vous pouvez étendre votre programme pour qu'il puisse être paramétrable à l'aide d'un fichier de configuration, dont vous choisirez librement le format. Toutefois, n'oubliez pas dans votre rapport d'en expliquer le fonctionnement et la manière de l'utiliser !

Conditions de développement

Le but de ce projet est moins de pondre du code que de développer le plus proprement possible. C'est pourquoi vous développerez ce projet en utilisant un serveur de gestion de versions tel que CVS, Subversion (SVN), GIT, etc.
Vous pouvez par exemple utiliser le serveur CVS mis à disposition des étudiants de l'Université à cette adresse : serveur CVS de l'université.
Comme nous attendons de vous que vous le fassiez sérieusement, votre rendu devra contenir un dump du fichier de logs des opérations effectuées sur votre projet, extrait depuis le serveur de gestion de versions que vous aurez choisi d'utiliser, afin que nous puissions nous assurer que vous avez bien développé par petites touches successives et propres (commits bien commentés), et non pas avec un seul commit du résultat la veille du rendu.

Conditions de rendu

Vous travaillerez en binômes et vous lirez avec attention la Charte des Projets. Vous rendrez votre projet au moyen d'un package Debian. Le rendu consistera donc en un mail dans lequel vous donnerez l'URL de votre repository, qui devra se trouver sur votre compte web de l'université. Le test de votre projet se fera avec la commande suivante :

sudo apt-get install docmycode

La commande docmycode doit alors être installée et doit pouvoir permettre la génération de la documentation d'applications développées en C et passées au programme comme indiqué plus haut. Naturellement, toutes les options que vous proposerez (ne serait-ce que --help) devront être gérées avec getopt et getopt_long.

Afin de pouvoir accéder aux sources de votre travail, vous préparerez également un package source contenant les choses suivantes :

un répertoire src contenant les sources du projet ainsi qu'un Makefile. Lorsqu'on lance make, on doit obtenir un exécutable nommé docmycode. La cible clean doit fonctionner correctement. Les sources doivent être propres, en anglais et commentées.
un fichier logs correspondant au dump des logs de votre projet, extrait depuis le serveur de gestion de versions que vous aurez utilisé.
un fichier rapport.pdf contenant votre rapport qui devra décrire votre travail. Si votre projet ne fonctionne pas complètement, vous devrez en décrire les bugs.
un dossier doc contenant la documentation technique de votre projet, générée à l'aide de votre programme docmycode exécuté sur les sources de votre programme.

Comme pour l'exécutable, l'accès à votre package source se fera au moyen de apt-get :

apt-get source docmycode

Remarques importantes :

L'intégralité de votre application doit être développée exclusivement en langage C (la documentation technique dynamique fait évidemment exception).
Toute utilisation de code dans un autre langage (y compris C++) vaudra ZÉRO pour l'intégralité du projet concerné.
En dehors des bibliothèques standards du langage C (telles que stdio.h, stdlib.h, string.h, getopt.h, etc.), il est interdit d'utiliser du code externe : vous devrez tout coder vous-mêmes.
Toute utilisation de code non développé par vous-mêmes vaudra ZÉRO pour l'intégralité du projet concerné.
Tout code commun à plusieurs projets vaudra ZÉRO pour l'intégralité des projets concernés.

Le projet est à rendre par mail à tous les enseignants (i.e. Guillaume Blin et Mathieu Chapelle).