> Tech > Documenter les sous-procédures

Documenter les sous-procédures

Tech - Par iTPro - Publié le 24 juin 2010
email

Si votre actuel système de documentation est bon, vous aimeriez peut-être continuer à l’utiliser. Toutefois, la méthode que je préfère est empruntée à JavaDoc et vous pouvez facilement écrire des programmes pour émuler le même processus pour RPG. Le langage Java permet de générer de la documentation à partir des

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.

Téléchargez gratuitement cette ressource

Aborder la Blockchain, comprendre et démarrer

Aborder la Blockchain, comprendre et démarrer

Une véritable révolution se prépare progressivement... les entreprises doivent veiller à ne pas rester à l’écart et se faire prendre de vitesse. Tout comme la mobilité ou encore le cloud, la blockchain est une composante essentielle de la transformation numérique. Découvrez, dans ce dossier, comment aborder, comprendre et démarrer la Blockchain

Tech - Par iTPro - Publié le 24 juin 2010