Lundi 17 janvier 2022

Générateur de documentation pour le C

Générer et afficher sur un terminal des commentaires encadrés par /** . . . */ à partir d'un fichier *.h, *.c, *.cc. Optionnellement produire un fichier html.

Présentation et motivation

Quand je code, j'ai parfois besoin d'avoir sous les yeux les commentaires des fonctions définies dans un autre fichier source, et même parfois dans le même.

Les outils qui existent sont assez laborieux à mon goût (doxygen par exemple).

J'ai donc opté pour la solution DIY, d'où cdoc.

Exemple de fragment code source C que cdoc va scruter et afficher :

/**
gets(s, size, stream)
Lit au plus size - 1 caractères depuis stream
et les range dans le tampons pointé par s. 
À la différence de fgets, si un caractère '\n' est lu, il n'est pas rangé.
Renvoie s si succès, et NULL sinon.
*/
char *gets(char *restrict, int, FILE *restrict);

Mon programme cdoc produit sur un terminal l'affichage suivant :

Le fichier html produit avec l'option d'un deuxième argument sur la ligne de commande est tout à fait similaire.

Utilisation

Dans le fichier source

cdoc reconnaît les blocs de commentaires encadrés par les balises /** et */.

cdoc va scruter les identificateurs de la déclaration de fonction qui suit immédiatement la fin du bloc de commentaires (dans l'exemple ci-dessus ce sont gets, s, size et stream) et va les ranger dans un lexique propre à ce bloc de commentaires.

Par la suite, dans toutes les lignes qui suivent et avant la ligne */, il les affichera en surbrillance. Idem pour le fichier html généré.

Lancer le programme

cdoc fichier.c

affichera sur le terminal la documentation trouvée dans fichier.c

Pour produire en plus un fichier html, la commande est :

cdoc fichier.c fichier.html

Ressource

• Le source du programme cdoc.c
• Il utilise une librairie que j'avais crée il y a quelques temps pour manipuler les chaînes de caractères text.h et text.c.