TP - Documentation technique de code
1. Présentation
Ce TP s’intéresse à la documentation technique du code source d’un logiciel, afin de le rendre plus facilement compréhensible et réutilisable. En particulier, vous verrez comment définir un README et des commentaires externes détaillés, et comment utiliser un outil pour générer une documentation complète à partir de tout cela.
-
La première partie de ce TP est un ensemble de notions, à savoir les principes de la documentation technique à l’aide notamment de commentaires externes ajoutés dans le code.
-
La seconde partie de ce TP est un travail pratique, où vous ferez un mini projet TypeScript que vous documenterez.
2. Notions sur la documentation technique
2.1. Pourquoi documenter ?
La documentation technique d’un logiciel est un ensemble d’informations expliquant comment son code source fonctionne, et comment il peut être (ré)utilisé pour du développement logiciel. Ce sont donc des informations dédiées à des développeurs. Deux catégories de développeurs sont susceptibles de lire cette documentation :
-
Les développeurs internes du code source documenté (qui sont eux même les auteurs de la documentation) souhaitant mieux comprendre certaines parties de leur propre logiciel, et mieux commuiniquer entre eux,
-
Les développeurs externes, qui n’ont pas développé le code source mais qui souhaitent en ré-utiliser le contenu au sein de leur propre projet logiciel, et qui ont donc pour cela besoin de documentation afin de bien comprendre comment faire usage de ce code.
À retenir : avoir accès à une documentation technique est crucial pour toute personne devant lire, utiliser ou modifier le code source d’un logiciel.
2.2. Quoi et comment documenter ?
Dans une documentation technique, on distinguera la documentation du projet dans son ensemble, et la documentation des différentes parties du code source.
2.2.1. Documenter le projet dans son ensemble
D’abord, la documentation du projet dans son ensemble comprend en règle générale :
-
une description du projet, de son but, des fonctionnalités,
-
des instructions pour configurer, compiler, installer le logiciel (si pertinent),
-
des instructions sur comment utiliser le logiciel,
-
une description de la structure du projet, en terme de répertoires, de fichiers, de code,
-
des informations sur la license logicielle utilisée,
-
des informations de contact.
Pour ce faire, il est d’usage d’écrire un fichier dit README
à la racine du projet logiciel.
C’est un fichier texte simple pouvant facilement être ouvert dans un éditeur de code, pour être facilement lisible par les développeurs.
Souvent, ce fichier suivra la syntaxe d’un format comme Markdown (et sera alors nommé README.md
) ou Asciidoc (et sera alors nommé README.adoc
, comme le présent document que vous êtes en train de lire !), afin d’être plus lisible et convertible en format HTML.
2.2.2. Documenter les différentes parties du code source
Ensuite, la documentation des différentes parties du code source comprend en règle générale (dans le cas de TypeScript) :
-
La description de chaque module (pour rappel, en TypeScript chaque fichier
.ts
est un module) : à quoi il sert, ce qu’il contient, ses relations avec d’autres modules. -
La documentation de chaque fonction présente dans le code du projet, avec :
-
Une description sur ce qu’elle réalise et à quoi elle sert,
-
Une description de chacun de ses paramètres,
-
Une description de sa valeur de retour (quand il y en a une),
-
Optionnellement, des indications sur comment la fonction réalise son but.
-
-
La documentation de chaque nouveau type de données (enregistrements, enumérations, etc.) présent dans le code du projet, avec :
-
Une description de ce que représente ce type de données,
-
Dans le cas des enregistrements, une description de chaque attribut.
-
Pour ce faire, une technique répandue est de directement écrire des commentaires externes à l’intérieur même du code source.
Comme une documentation technique peut être assez verbeuse, on utilise généralement des blocs de commentaires, aussi appelés commentaires multi-lignes (/* */
en TypeScript).
Ainsi, une personne lisant le code source aura directement sous les yeux la documentation technique associée, ce qui lui permettra de plus facilement et rapidement comprendre à quoi sert le code et comment il fonctionne.
C’est particulièrement utile pour les développeurs internes.
Pour rappel, on appelle commentaire interne un commentaire présent à l'intérieur d’une fonction, et on appelle commentaire externe un commentaire qui est à l’extérieur d’une fonction. Attention : cela n’a rien à voir avec la notion de développeur interne ou externe ! |
2.2.3. Générer une documentation technique externe
Enfin, si les commentaires sont bien écrits et suivent une structure précise et imposée, il est possible d’utiliser un outil automatique capable de lire le README
et les commentaires afin de générer automatiquement une documentation lisible en dehors du code source, souvent sous format HTML ouvrable dans un navigateur.
Pouvoir parcourir la documentation de manière séparée du code est particulièrement utile pour les développeurs externes.
Voyons maintenant comment faire tout cela concrètement avec l’outil TypeDoc pour TypeScript !
2.3. Écriture et génération de documentation à l’aide de TypeDoc
2.3.1. Présentation de TypeDoc
TypeDoc est un outil communautaire capable de générer une documentation technique externe à partir d’un projet TypeScript bien commenté et configuré. Il produit une jolie documentation en format HTML qu’il est ensuite possible de visionner dans un navigateur web.
Pour générer une documentation technique structurée, TypeDoc est capable de lire certain nombre d'étiquettes (tags en anglais) au sein des commentaires externes.
Elles prennent la forme @etiquette
, et permettent soit de donner des informations supplémentaires sur les éléments documentés (ex. @param
pour indiquer un paramètre d’une fonction), soit d’influencer la génération de documentation (ex. @ignore
pour indiquer que quelque chose ne doit pas être documenté).
Voyons maintenant comment documenter les différentes parties d’un projet TypeScript : le projet dans son ensemble, un module, une fonction, et un enregistrement.
2.3.2. Documenter le projet dans son ensemble
Pour documenter un projet dans son ensemble, il faut créer un fichier appelé README.md
, et le remplir avec les informations choisies.
Le contenu de ce fichier sera automatiquement utilisé pour remplir la page d’accueil de la documentation technique générée par TypeDoc.
L’extension .md signifie que le fichier suit la syntaxe du langage Markdown.
Pour ce cours, ce n’est pas nécessaire de connaître Markdown, et vous pouvez écrire du simple texte dans ce fichier, malgré son extension.
|
2.3.3. Documenter un module
En TypeScript, on appelle module un fichier contenant du code TypeScript.
Pour documenter un module avec TypeDoc, on écrit un bloc de commentaire au tout début du fichier, et on ajoute l’étiquette @module
à la fin de ce bloc.
/**
* Set of functions to build geometric shapes using Points.
*
* @module
*/
Le contenu d’un tel commentaire de module sera automatiquement utilisé au début de la page de documentation du dit module, dans la documentation technique générée par TypeDoc.
2.3.4. Documenter une fonction
Pour documenter une fonction avec TypeDoc, on écrit un bloc de commentaire juste avant la fonction, et on utilise les deux étiquettes suivantes :
-
@param
permet de décrire un des paramètres de la fonction, -
@returns
permet de décrire ce que rend cette fonction.
/**
* Creates a Segment using two Points.
* @param point1 The first end of the segment.
* @param point2 The second end of the segments.
* @returns The segment created from the two points.
*/
function createSegment(point1: Point, point2: Point) : Segment { ... }
2.3.5. Documenter un type de données
Pour documenter un type de données avec TypeDoc (ex. enregistrement ou énumération), on écrit un bloc de commentaire juste avant la déclaration du type.
Dans le cas d’un enregistrement, on écrit également un bloc de commentaire pour chacun de ses attributs.
Aucune étiquette particulière est nécessaire.
/**
* Represents a point on an Euclidean plane.
*/
type Point = {
/**
* Abscissa.
*/
x: number,
/**
* Ordinate.
*/
y: number
}
/**
* Represents the direction of a given element.
*/
enum Direction {
Up,
Down,
Left,
Right
}
2.3.6. Autres étiquettes utiles
TypeDoc fournit d’autres étiquettes pouvant être utiles, notamment les deux suivantes :
-
@ignore
pour indiquer qu’aucune documentation ne doit être généré pour cet élément, -
@category
pour regrouper différents éléments d’un module au sein d’une catégorie.
2.3.7. Configurer un projet et exécuter TypeDoc
Pour pouvoir exécuter TypeDoc sur un projet bien commenté, il faut déclarer TypeDoc comme dépendance, et configurer une nouvelle commande pour appeler TypeDoc.
Pour cela, il faut ajouter au projet le fichier package.json
suivant (qui ressemble à celui du TP sur le test), en remplaçant mon_projet
par le nom que vous souhaitez donner à votre projet :
{
"name": "mon_projet",
"scripts": {
"docs": "typedoc --readme README.md --entryPointStrategy expand src"
},
"devDependencies": {
"typedoc": "0.25.8"
}
}
Puis, pour installer les dépendances spécifiées dans package.json
(et donc TypeDoc), il faut ouvrir un terminal, vous rendre dans le répertoire de votre projet, et exécuter la commande suivante :
$ npm install
Enfin, pour appeler TypeDoc, vous pouvez appeler la commande suivante :
$ npm run docs
Normalement TypeDoc va produire un répertoire docs
contenant des fichiers HTML.
Vous pouvez ouvrir le fichier docs/index.html
dans un navigateur web, et contempler votre documentation technique !
Vous pouvez notamment aller de module en module à l’aide de la barre de navigation tout à droite.
3. Exercice pratique : Jeu de cartes
Dans cette partie, vous allez appliquer ces notions pour coder et documenter un petit projet TypeScript de développement de fonctions pour manipuler un jeu de 52 cartes classique.
3.1. Préparation du projet
-
Créez un nouveau projet privé sur le Gitlab de l’université, avec le nom que vous souhaitez.
-
Clonez avec
git
votre dépôt sur votre ordinateur de travail, ce qui vous donnera un nouveau répertoire. -
Ouvrez un terminal, allez dans le répertoire, et préparez le contenu suivant :
-
Un fichier
tsconfig.json
avec le contenu habituel. -
Un fichier
package.json
comme expliqué dans la partie cours présentée plus haut. -
Un fichier
.gitignore
contenant la liste de tous les répertoires qui seront générés et donc que l’on ne voudra pas versionner avec git, à savoir :node_modules docs build
-
-
Effectuez un commit qui ajoute ces trois fichiers à votre dépôt git, et effectuez un push qui envoie ce commit dans votre dépôt Gitlab distant.
-
Enfin, ouvrez ce répertoire dans Visual Studio Code. Vous êtes prêt à commencer !
Tout au long de cet exercice, appliquez bien tout ce qui a été vu en TP Gitlab, et pensez à faire des commits et des push régulièrement ! |
3.2. Implémentation et documentation
Dans votre projet, créez un répertoire src
(comme d’habitude), et implémentez et documentez tous les éléments suivants.
-
Un module
card
, qui permet de créer des cartes et de les manipuler. Ce module doit comprendre :-
Une enumération
Color
qui définit les différentes couleurs d’un jeu de carte (pique, carreau, trèfle et cœur), -
Un enregistrement
Card
qui permet de représenter des cartes, chacune avec une couleur et une valeur allant de 2 à 14 (note: on peut considérer que le valet vaut 11, la dame 12, le roi 13, et l’as 14). -
Une fonction
createCard
pour créer une carte à partir d’un couleur et d’une valeur. -
Une fonction
displayCard
qui affiche une carte dans la console (conseil : utiliser les emojis ♣️,♦️,♥️,♠️). -
Une fonction
compareCard
qui prend deux cartes et renvoie une valeur positive si la première carte est plus forte, zéro si elles ont les mêmes valeurs, et une valeur négative si la première carte est moins forte.
-
-
Un module
game
qui permet de créer et manipuler un jeu de cartes, avec :-
Une fonction
createGame
qui renvoie l’ensemble des 52 cartes possibles sous la forme d’un tableau. -
Une fonction
drawCard
qui retire la première carte d’un tableau de cartes, et qui la rend en valeur de retour.
-
N’oubliez pas d’également (brièvement) documenter le projet dans son ensemble avec un README.md ! Voir la partie du cours concernée plus haut.
|
Il se peut que vous ayez besoin de retirer des éléments à un tableau, ou alors d’insérer des éléments au milieu d’un tableau.
Pour cela, il existe en TypeScript une fonction utilitaire appelée
|
3.3. Génération de documentation HTML avec TypeDoc
Au fur et à mesure que vous implémentez et documentez votre code, générez la documentation HTML à l’aide de TypeDoc. Voir la partie du cours concernée plus haut.
Dernier conseil :
Retenez que le but de cet exercice est d’apprendre à écrire une documentation technique !
|