C ++: la création de la documentation avec doxygen

La plupart des programmeurs détestent pour créer la documentation encore plus qu'ils détestent pour commenter leur propre code. Entrez Doxygen, qui permet aux programmeurs d'intégrer des tags dans les commentaires qui peuvent ensuite être extraites pour créer la documentation.

Installation Doxygen

Doxygen ne vient pas avec Code :: Blocks (du moins pas de cette écriture). Vous aurez besoin de télécharger la bonne version de Doxygen pour votre application. (Il ya aussi un lien vers le site à partir du site Doxygen Code :: Blocks.) Après vous lien vers le site Doxygenorg, vous pouvez naviguer vers la page de téléchargement et de trouver la version de Doxygen pour votre système d'exploitation, comme indiqué ici:

Télécharger et installer la version qui est bon pour votre système d'exploitation. Vous pouvez accepter les valeurs par défaut, mais rappelez-vous où l'assistant d'installation place le fichier exécutable Doxygen.

Maintenant commencer Code :: Blocks. Sélectionnez-DoxyBlocks Ouvrez les Préférences. De là, sélectionnez l'onglet Général et définissez le chemin à Doxygen. (Ceci est le chemin que vous avez noté dans le paragraphe précédent). Le chemin par défaut pour Windows est C: Program Files doxygen bin doxygen.exe. Faites de même pour la voie de Doxywizard. Voici la valeur par défaut pour Windows est C: Program Files doxygen bin doxywizard.exe. Vous pouvez laisser les autres outils vierge car ils ne sont pas nécessaires lors de la génération de documentation au format HTML.

Ajout de commentaires de documentation

Doxygen utilise commentaires spéciaux à des mots-clés de drapeau qui aident l'outil Créer la documentation. Assez confuse, Doxygen accepte plusieurs normes différentes, mais la valeur par défaut est celui qui ressemble le plus à JavaDoc, la / ** commenter, ce qui est bien. (Vous pouvez changer le style de commentaire à l'un des autres en sélectionnant DoxyBlocks-Ouvrez les Préférences, puis en sélectionnant l'onglet Commentaire Style.)

Pour voir comment cela fonctionne, placez le curseur au début d'une fonction et sélectionnez DoxyBlocks-Block Commentaire (ou appuyez sur Ctrl + Alt + B). Un commentaire ci-dessous apparaît (les exemples suivants utilisent le programme Budget5 qui apparaît dans le matériel téléchargeable au godiches.com/extras/cplusplus):

/ ** Brève ** param liste de accList* Retourner void ** / getAccounts vides (liste accList) {

Code :: Blocks insère un bloc de commentaire commençant par Doxygen / **. Doxygen sait que ce commentaire appartient à la définition de la fonction qui suit immédiatement. Mots-clés Doxygen commencent avec un (barre oblique inverse). La bref drapeaux de mots-clés de la brève description de la fonction. La brève description peut étendre sur plus d'une ligne. Cela devrait être une courte description de la fonction qui apparaît dans affichages tabulaires.

Le programmeur peut suivre cela avec une description plus approfondie signalé avec le détails mot-clé. Cette description détaillée donne une description plus approfondie de ce que fait la fonction.

Un grand nombre de mots-clés Doxygen sont facultatifs. En particulier, la détails mot-clé est supposé si vous commencez un paragraphe séparé de la bref Description rien que par une ligne blanche.

Au-delà qui est une ligne distincte signalé avec le mot-clé param pour décrire chaque argument de la fonction. Enfin, la retour mot-clé décrit la valeur renvoyée par la fonction.

Lorsque rempli, le commentaire pour Doxygen getAccounts () pourrait apparaître comme suit:

/ ** Brèves getAccounts - comptes d'entrées depuis le clavier * informations Cette fonction lit l'entrée à partir du clavier * Pour chaque S ou C est entré, la fonction crée une nouvelle épargne * ou Vérification objet de compte et il ajoute à la * liste des comptes. . Un X termine l'entrée. * Toute autre entrée est supposé être un dépôt (nombres supérieurs à 0 *) ou un retrait (nombres inférieurs à 0). ** Param liste de accList la liste de compte * objets créés par getAccounts () * * / retourner void getAccounts vides (liste accList) {

Vous pouvez également ajouter un commentaire Doxygen sur la même ligne. Ceci est le plus souvent utilisé en commentant les membres de données. Placez le curseur à la fin de la ligne et sélectionnez soit DoxyBlocks-Line Commentaire ou appuyez sur Ctrl + Alt + L. Maintenant remplir une description de l'élément de données. Le résultat apparaît comme dans l'exemple suivant également pris de Budget5:

à double équilibre - / ** lt; le solde du compte courant * /

Génération de la documentation Doxygen

Doxygen peut générer de la documentation dans plusieurs formats différents, même si certains (tels que HTML compilé) Exiger que d'autres téléchargements. Le format HTML est particulièrement pratique car il nécessite rien de plus qu'un navigateur pour afficher.

La valeur par défaut est HTML, mais si vous voulez changer le format sélectionnez-DoxyBlocks Ouvrez les Préférences, puis sélectionnez les paramètres par défaut Doxyfile 2 onglet. Dans cette fenêtre, vous pouvez sélectionner tous les différents formats que vous souhaitez générer.

Avant d'extraire la documentation la première fois, vous aurez probablement envie de choisir quelques autres options. Sélectionnez-DoxyBlocks Ouvrez les Préférences, puis sélectionnez l'onglet Par défaut Doxyfile. Assurez-vous que l'extrait Toutes case est cochée. Ensuite, sélectionnez l'onglet Doxyfile par défaut 2 et vérifier les Class_Diagrams case à cocher. Maintenant, sélectionnez l'onglet Général et cochez la case Exécuter HTML Après la compilation. Cliquez sur OK, et vous avez terminé. (Vous ne serez pas besoin de faire cela à nouveau que les options sont enregistrées dans un fichier appelé Doxyfile.)

Sélectionnez Documentation DoxyBlocks-Extrait de générer et de consulter la documentation. Après un assez court intervalle, Doxygen ouvre votre navigateur préféré avec la documentation tel que représenté dans la figure suivante.

Doxygen est pas très convivial quand il vient à des erreurs de saisie. Parfois Doxygen arrête juste génération de la documentation à un certain point dans votre source pour aucune raison évidente. Vérifiez le fichier de doxygen.log contenue dans le même répertoire que le Doxyfile pour les erreurs qui ont pu se produire lors de l'extraction.

L'image suivante montre le navigateur de projet dans la fenêtre de gauche qui permet à l'utilisateur de naviguer dans la documentation du projet. Sur la droite, la getAccounts () fonction a été sélectionnée afin d'obtenir une description plus détaillée. La brève description apparaît sur la première ligne, suivi par la description détaillée, les paramètres, et la valeur de retour:

La documentation de la classe est similaire approfondie comme le montre l'extrait de code suivant.

/ ** Compte de classe * Brève un compte bancaire * abstraite de détails Cette classe abstraite intègre * propertiescommon aux deux types de compte:. * Vérification et d'épargne. Cependant, il manque le concept de retrait * (), qui est différent entre le compte * * / bi-classe {

La documentation de Considération est montré ici:

Remarquez la description qui apparaît dans la catégorie Considération. Ceci est la brève description. En cliquant sur Plus vous amène à la description détaillée. Notez également la représentation graphique de la relation d'héritage entre Considération, ses classes parentes, et ses classes enfants.