Documenter les sous-procédures

commentaires du code source. Des identificateurs spéciaux (étiquettes de commentaires) servent à identifier les commentaires qui serviront à générer la documentation. La documentation ainsi obtenue se présente sous la forme de pages Web.

En RPG, les prototypes sont le moyen le plus simple d’appliquer une telle fonction. La figure 4 montre des commentaires de documentation spéciaux codés pour un prototype. Le **/ sur la première ligne de commentaire indique que c’est le début d’un ensemble de commentaires de documentation pour un appel prototypé. Les étiquettes de commentaires individuelles commencent par le symbole @. Les noms et les définitions proviennent du prototype lui-même. Le programme d’analyse effectue aussi une « validation de la documentation », pour s’assurer que tous les commentaires requis (description, auteur, catégorie, par exemple) sont entrés et que tous les paramètres et valeurs de renvoi sont documentés. Les étiquettes de commentaires dans la figure sont les suivantes :

• @desc – description ce que fait la procédure
• @author – qui a écrit la procédure
• @return – description de la valeur (éventuelle) renvoyée par la procédure
• @param – description d’un paramètre passé vers ou à partir de la procédure ; chaque paramètre a besoin d’une définition @param
• @category – la catégorie à laquelle appartient la procédure ; une procédure doit appartenir à une catégorie au moins et peut appartenir à plusieurs

Bien entendu, vous pouvez identifier les étiquettes de commentaires que vous jugez appropriées à votre mode de documentation des procédures. Dans cet exemple, l’étiquette de commentaire importante concerne les catégories. En classant les procédures par catégories, vous permettez aux programmeurs de trouver plus facilement une procédure.

Un programme d’analyse scrute et analyse les membres source prototype et génère des tables d’information à références croisées, facilement accessibles par une interface Web. Ou bien, le programme d’analyse peut générer un jeu de pages Web statiques, de la même manière que la commande GENCMDDOC (Generate Command Documentation) le fait pour des commandes CL.

Dans les deux cas, vous devriez être à même de présenter l’information dans une interface Web. Ma préférence personnelle va CGIDEV2. Pour trouver la définition d’une sous-procédure, sélectionnez d’abord une catégorie de procédure (figure 5). Vous obtenez la liste de toutes les procédures dans cette catégorie. Choisissezen une pour voir sa définition complète (figure 6).

Vous pouvez ajouter la possibilité de rechercher des noms de procédures qui contiennent un certain mot (par exemple, toutes les procédures contenant le mot « produit »). Et aussi ajouter la possibilité d’utiliser d’autres critères de recherche de définitions.