Auto-documentation assistée de logiciels : génération et maintenance de fichiers README avec l'outil Nitreadme

Terrasa, Alexandre (2019). « Auto-documentation assistée de logiciels : génération et maintenance de fichiers README avec l'outil Nitreadme » Thèse. Montréal (Québec, Canada), Université du Québec à Montréal, Doctorat en informatique.

Fichier(s) associé(s) à ce document :
[img]
Prévisualisation
PDF
Télécharger (15MB)

Résumé

Le fichier README est typiquement le premier artefact de documentation vu par les utilisateurs d'un projet logiciel - sa page de couverture. Ce fichier permet de présenter les objectifs d'un logiciel, ses fonctionnalités, son utilisation, etc. Selon une étude empirique que nous avons réalisée sur GitHub, la plate-forme de partage de code la plus populaire au monde, 99% des projets contiennent un tel fichier. Les fichiers README sont écrits selon une structure et un ordre plus ou moins standardisés, et notre étude montre que certaines sections sont communes à la plupart, par ex., installation, signalement de bogues, licence, etc. Étrangement, une part importante des informations rédigées à la main pour la présentation des API - par ex., listes de classes et de propriétés, documentation de ces entités, exemples d'utilisation - correspond à ce qui est habituellement produit de manière automatisée par les outils d'auto-documentation d'API tels que Javadoc ou Doxygen. Nous proposons donc une approche permettant d'assister !'écrivain de fichiers README, tant durant la rédaction que la maintenance. Lors de la rédaction, notre approche consiste à suggérer des cartes de documentation, i.e., des extraits de documentation produits par le générateur de documentation d'API pouvant être importés directement dans le corps du README. Puis, durant la maintenance, notre approche assure que le contenu de ces cartes soit tenu synchronisé avec le code source. La mise en oeuvre de notre approche repose sur l'alignement du contenu du fichier README avec le contenu de l'API qu’il documente, c'est-à-dire l'établissement de correspondances entre les éléments clés du README et les entités du code source. Ceci permet de sélectionner les cartes de documentation pertinentes à insérer ainsi que les positions où les insérer dans le document. La principale contribution de notre travail se matérialise dans la conception et la mise en oeuvre d'une suite d'outils pour la production de fichiers README, entre autres, nitweb/readme, un outil de rédaction semi-assisté de README faisant des suggestions à l'écrivain de façon interactive, et ni treadme, un outil de suggestion pour les fichiers README en ligne de commande pouvant générer de nouveaux fichiers à partir du code (approche a priori) ou améliorer des README existants et les tenir synchronisés avec le code (approche a posteriori). _____________________________________________________________________________ MOTS-CLÉS DE L’AUTEUR : documentation logicielle, auto-documentation, API, fichier README, Markdown, alignement

Type: Thèse ou essai doctoral accepté
Informations complémentaires: La thèse a été numérisée telle que transmise par l'auteur.
Directeur de thèse: Privat, Jean
Mots-clés ou Sujets: Documentation du logiciel / Interfaces de programmation d'applications / Fichier Lisez-moi / Langage Nit
Unité d'appartenance: Faculté des sciences > Département d'informatique
Déposé par: Service des bibliothèques
Date de dépôt: 10 oct. 2019 14:10
Dernière modification: 10 oct. 2019 14:10
Adresse URL : http://archipel.uqam.ca/id/eprint/12839

Statistiques

Voir les statistiques sur cinq ans...