Hé bien ces temps-ci mon blog croule sous les articles, va falloir que je me calme moi… non ? Bon, je vais donc vous parler de mon dernier né, qui incube quand-même depuis un moment…
Une petite histoire, ça vous dit ?
Une petite histoire… tout commence il y a bien longtemps, du temps où l’année s’écrivait encore 2009. En ces temps reculés donc, et en grand amateur de documentation fraîche et bien formée1, l’idée d’écrire un plugin pour cet EDI2 sympathique qu’est Geany qui faciliterai la rédaction de la documentation d’un code source germa dans mon esprit. Ni d’une ni de deux, je m’attèles à la tâche. Sauf que je me rends compte rapidement que le design de mon plugin est tout sauf le bon. Je voulais quelque-chose d’extensible : c’est on ne peut plus fermé. Je voulais quelque chose qui gère facilement à peu près n’importe quel langage de programmation : c’est tout sauf le cas. Je voulais quelque-chose qui soit à peu près indépendant du format de documentation : que nenni ! J’arrête donc les efforts inutiles, et me penches sur un design plus adapté… mais, et c’est ce qui va me perdre, j’ai quand-même déjà quelque-chose qui fonctionne relativement bien pour mes besoins.
Et donc, le temps passe et j’oublie un peu mon devoir d’améliorer ce design ; et ceci est, je l’avoue volontiers, en grande partie dû au fait que le mauvais plugin fonctionnait trop bien, satisfaisant la majorité de mes besoins. Le temps passe donc, et je ne réfléchis que distraitement à ce nouveau design.
Mais, bien-entendu, arrive un moment où je trouve une idée qui me paraît adaptée — l’avenir nous le dira — et je commences donc à l’implémenter. Mais ha ha, je me heurtes à un léger problème : j’ai besoin d’un moteur de template qui permet d’utiliser des boucles et autres tests. J’ai beau chercher de-ci de-là, rien (en C) ne semble correspondre à mes besoins. Car en plus je suis difficile, et ne veux pas avoir à appeler un programme externe mais préfère une bibliothèque, et si elle permettait de traiter des données directement en mémoire, ça serait encore mieux. Et c’est ainsi qu’est né ce fameux CTPL dont je vous parle tout le temps.
Et donc me voici en train d’écrire CTPL, mettant à nouveau en pause le plugin lui-même. Quelques mois passent tranquillement sans en avoir l’air… et finalement, CTPL arrive à un stade qui semble utilisable.
Me revoici donc à implémenter ce plugin nouveau, chose enfin possible ! Et les choses se passent tranquillement, entre écriture et changement de certaines choses dans CTPL, pour arriver finalement au stade actuel : ça marche plutôt bien, et le design me semble plutôt sympathique.
GeanyGenDoc, enfin !
Et me voici enfin à présenter ce plugin, le simplement nommé GeanyGenDoc.
C’est quoi ?
GeanyGenDoc est sensé faciliter la rédaction de la documentation d’un code source. Son rôle est de préparer le terrain pour recevoir ce qui est vraiment utile, c’est à dire les descriptions et autres explications. Il génères donc, à la demande, un commentaire de documentation vide adapté à ce qu’il documente. Par exemple, il préparera un commentaire de fonction Doxygen en insérant automatiquement la liste des paramètres : il ne reste plus qu’à remplir les descriptions. Évidemment, on peut en faire autant avec les structures, les énumérations, les variables, et cætera.
Les fonctionnalités et le reste
GeanyGenDoc a été conçu pour être à peu près complètement extensible ; ce qui fait que la majeur partie des choses sont configurables :
- Utilisation de templates définies par l’utilisateur pour les commentaires de documentation ;
- Règles de documentation définies par l’utilisateur (s’il faut documenter ceci, cela, autre-chose, si c’est en fait le parent qui doit s’en occuper, etc.) ;
- Utilisation de l’arbre de tags de Geany comme source de symboles, permettant de gérer à peu près tous les langages connus de Geany, et ce sans ajout de code.
J’en oublie sans doutes, mais voici les choses principales. S’il me fallait citer un inconvénient à ce design, je pense que je dirais que son défaut vient de son extensibilité et de sa jeunesse : il faut écrire la plupart des règles de documentation car très peu sont fournies par défaut. Pour le moment il n’y a que GTK-Doc en C qui soit géré plutôt correctement par défaut, et une petite partie de Doxygen. Mais des règles pour d’autres langages ou formats de documentation seront probablement intégrées par défaut au fur et à mesure.
Se procurer GeanyGenDoc
GeanyGenDoc n’a encore aucune version publiée, mais la version de développement se trouve dans le dépôts de plugins de Geany, Geany-Plugins. Amusez-vous, documentez, rapportez des bugs et fournissez des patchs !
Vous pouvez accéder au dépôt avec SVN :
svn co https://geany-plugins.svn.sourceforge.net/svnroot/geany-plugins/trunk geany-plugins
Et même avec Git directement (sans même avoir besoin de git-svn) :
git clone http://git.geany.org/git/geany-plugins