@@ -9,7 +9,7 @@ En particulier, vous verrez comment définir des _commentaires externes_ détail
WARNING: Cette partie du cours n'est *pas optionnelle* !
Pour l'examen, vous devez comprendre les principes présentés ici et être capables de refaire les exercices.
- Dans une _première partie_ ous allez découvrir les principes de la documentation technique à l'aide de commentaires externes ajoutés dans le code.
- Dans une _première partie_ vous allez découvrir les principes de la documentation technique à l'aide de commentaires externes ajoutés dans le code.
- Dans une _seconde partie_, vous ferez un mini projet TypeScript que vous documenterez.
- Dans une _troisième partie_, vous appliquerez ce que vous aurez appris sur le projet Pokémon (déjà croisé lors du TP Gitlab).
...
...
@@ -21,11 +21,12 @@ La *documentation technique* d'un logiciel est un ensemble d'informations expliq
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,
- Les _développeurs externes_ qui souhaitent utiliser le code source documenté 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.
- 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.
Ainsi, il est courant de documenter ce que fait une fonction (notamment son but, ses effets, ses paramètres, sa valeur de retour), un type de données (comme une interface TypeScript), ou une simple valeur constante.
La documentation technique est cruciale pour toute personne devant lire, utiliser ou modifier le code source d'un logiciel.
En somme, la documentation technique est cruciale pour toute personne devant lire, utiliser ou modifier le code source d'un logiciel.
// Plus précisément, il est courant de documenter ce que fait une fonction (notamment son but, ses effets, ses paramètres, sa valeur de retour) ainsi que chaque type de données (comme une interface TypeScript).
=== Quoi et comment documenter ?
...
...
@@ -82,7 +83,7 @@ interface Point {
```
====
Puis, si les commentaires sont bien écrits et suivent une structure précise et imposée, il est également possible d'utiliser un outil automatique capable de lire les commentaires, afin de *générer automatiquement une documentation lisible en dehors du code source*, souvent sous format HTML ouvrable dans un navigateur.
Puis, si les commentaires sont bien écrits et suivent une structure précise et imposée, il est également possible d'utiliser un outil automatique capable de lire les commentaires et 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* !
