C ++: création de documentation avec Doxygen - mannequins

La plupart des programmeurs détestent créer de la documentation encore plus qu'ils ne détestent commenter leur propre code. Entrez Doxygen, ce qui permet aux programmeurs d'incorporer des balises dans les commentaires qui peuvent ensuite être extraits pour créer la documentation.

Installation de Doxygen

Doxygen n'est pas fourni avec Code:: Blocs (du moins pas à ce jour). Vous devrez télécharger la version appropriée de Doxygen pour votre application. (Il existe également un lien vers le site Web Doxygen à partir du site Code:: Blocks.) Après avoir lié le site Doxygenorg, vous pouvez accéder à la page de téléchargement et trouver la version de Doxygen pour votre système d'exploitation:

Téléchargez et installez la version adaptée à 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, commencez Code:: Blocks. Sélectionnez DoxyBlocks → Ouvrir les préférences. De là, sélectionnez l'onglet Général et définissez le chemin vers 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 Filesdoxygenbindoxygen. EXE. Faites de même pour Path to Doxywizard. Ici, la valeur par défaut pour Windows est C: Program Filesdoxygenbindoxywizard. exe . Vous pouvez laisser les autres outils vides car ils ne sont pas nécessaires lors de la génération de la documentation au format HTML.

Ajout de commentaires de documentation

Doxygen utilise des commentaires spéciaux pour marquer les mots-clés qui aident l'outil à créer de la documentation. Assez confusément, Doxygen accepte plusieurs normes différentes, mais la valeur par défaut est celle qui ressemble le plus à JavaDoc, le commentaire / ** , ce qui est très bien. (Vous pouvez changer le style de commentaire pour l'un des autres en sélectionnant DoxyBlocks → Ouvrir les préférences, puis en sélectionnant l'onglet Style de commentaire.)

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

/ ** brief * * param accList list & * return void * * / void getAccounts (list & accList) {

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

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

De nombreux mots-clés Doxygen sont facultatifs. En particulier, le mot-clé détails est supposé si vous démarrez un paragraphe séparé de la description brief par rien de plus qu'une ligne vide.

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

Une fois rempli, le commentaire Doxygen pour getAccounts () peut apparaître comme suit:

/ ** bref getAccounts - entrée des comptes depuis le clavier * détails Cette fonction lit les entrées du clavier. * Pour chaque S ou C saisi, la fonction crée un nouvel objet de compte * Épargne ou Checking et l'ajoute à la liste des comptes *. Un X termine l'entrée. Toute autre * entrée est supposée être un dépôt (nombre supérieur à * 0) ou un retrait (nombre inférieur à 0). * * liste param accList & la liste des objets account * créés par getAccounts () * return void * / void getAccounts (liste & accList) {

Vous pouvez également ajouter un commentaire Doxygen sur la même ligne. Ceci est le plus souvent utilisé lorsque vous commentez des membres de données. Placez le curseur à la fin de la ligne et sélectionnez DoxyBlocks → Commentaire de ligne ou appuyez sur Ctrl + Alt + L. Maintenant remplissez une description du membre de données. Le résultat apparaît comme dans l'exemple suivant également tiré du Budget5:

double balance; / ** 

Génération de la documentation Doxygen
Doxygen peut générer de la documentation dans plusieurs formats différents, bien que certains (comme le code HTML compilé) nécessitent d'autres téléchargements. Le format HTML est particulièrement pratique car il ne nécessite rien de plus qu'un navigateur pour voir.
La valeur par défaut est HTML, mais si vous souhaitez modifier le format, sélectionnez DoxyBlocks → Ouvrir les préférences, puis sélectionnez l'onglet Doxyfile Defaults 2. Dans cette fenêtre, vous pouvez sélectionner tous les différents formats que vous souhaitez générer.
Avant d'extraire la documentation pour la première fois, vous voudrez probablement sélectionner quelques autres options. Sélectionnez DoxyBlocks → Ouvrir les préférences, puis sélectionnez l'onglet Doxyfile Defaults. Assurez-vous que la case Extraire tout est cochée. Ensuite, sélectionnez l'onglet Doxyfile Defaults 2 et cochez la case Class_Diagrams. Maintenant, sélectionnez l'onglet Général et cochez la case Exécuter le code HTML après la compilation. Cliquez sur OK, et vous avez terminé. (Vous n'aurez plus besoin de le faire car les options sont sauvegardées dans un fichier appelé doxyfile.)
Sélectionnez DoxyBlocks → Extract Documentation pour générer et afficher la documentation. Après un intervalle assez court, Doxygen ouvre votre navigateur préféré avec une documentation comme celle montrée dans la figure suivante.
Doxygen n'est pas très convivial lorsqu'il s'agit d'erreurs de saisie. Parfois, Doxygen arrête juste de générer de la documentation à un moment donné dans votre source sans raison apparente.Vérifiez le doxygen. fichier journal contenu dans le même répertoire que le fichier doxyfile pour les éventuelles erreurs survenues 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 fonction getAccounts () 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, suivie de la description détaillée, des paramètres et de la valeur de retour:

La documentation de la classe est similaire, comme l'indique l'extrait de code suivant.
/ ** class Account * résume un compte bancaire abstrait. * details Cette classe abstraite incorpore * propertiescommon aux deux types de compte: * Vérification et économies. Cependant, il manque le * concept de retrait (), qui est différent * entre les deux * / class Account {

La documentation pour Account est affichée ici:

Notez la description qui apparaît sous le class Compte . Voici la brève description. Cliquer sur Plus vous amènera à la description détaillée. Notez également la représentation graphique de la relation d'héritage entre Account , ses classes parentes et ses classes enfants.