The K Desktop Environment

Page suivante Page précédente Table des matières

10. Documentation de Classe avec KDoc

Une autre partie importante de la documentation est la description informative des interfaces de votre classe. Cela vous permettra, ainsi qu'à d'autres programmeurs, d'utiliser vos classes en lisant la documentation HTML de la classe qui peut être générée avec KDoc. KDevelop supporte pleinement l'utilisation de KDoc pour créer la documentation des bibliothèques de KDE, ainsi vos architectures d'applications sont déjà documentées. Un bon point de départ, avant que vous ne rentriez vous-même dans le code fourni, est de lire la documentation en-ligne qui est incluse. Dans la suite, nous décrirons comment obtenir la documentation de l'API (NdT : Interface de Programmation d'Application, littéralement Application Programming Interface), où KDevelop vous permet de l'ajouter et quels sont les types de balises spéciales fournies en plus par KDoc.

10.1 Comment utiliser les Fonctionnalités de Documentation de KDevelop

Pour créer la documentation de l'API après avoir généré votre projet, sélectionnez "Construire la documentation de l'API" dans le menu "Projet". Cela traitera tous les fichiers d'en-tête et créera la sortie HTML. Ensuite, vous pourrez accéder à la documentation en choisisant "Documentation de l'API" dans le menu "Aide" ou bien le symbole de livre correspondant dans l'arborescence "Documentation", dossier "Projet courant".

La documentation contient déjà des références croisées entre les documentations en-ligne des classes de Qt et de KDE. Ainsi, vous pouvez suivre facilement l'héritage avec l'aperçu de l'héritage. Cela peut aussi vous aider à débuter avec les documentations de Qt et de KDE.

10.2 Ajouter la Documentation d'une Classe ou d'un Membre

De même que KDevelop fournit tous les moyens d'ajouter automatiquement du code, il offre aussi directement de la documentation. Lorsque vous utilisez le Générateur de classe en choisissant "Projet"->"Nouvelle classe", ajoutez un message d'aide descriptif dans la zone de documentation. Cela ajoutera la documentation dans l'en-tête de la classe.

Lorsque vous ajoutez des fonctions membres et des attributs avec les outils de classe, ajoutez aussi la documentation du membre de la classe dans les zones de documentation correspondantes. Vous pourriez penser que la documentation est une partie du processus de développement qui n'est pas vraiment nécessaire. Mais souvenez-vous que plus votre projet grandit et plus il y aura de personnes à prendre part au processus de développement, la documentation des classes est alors la meilleure façon de ne pas perdre du temps. Si les développeurs doivent deviner, par le nom des méthodes, ce que fait réellement la méthode, c'est probablement que la sémantique n'est pas comprise et la méthode ne réalise pas la tâche à laquelle le développeur s'attendait. C'est pourquoi vous devez garder une trace de votre documentation et la regénérer aussi souvent que possible.

Par ailleurs, les fichiers de documentation ne sont PAS inclus dans le projet, et ne supportent pas non plus l'internationalisation. C'est pourquoi la documentation de l'API doit être réalisée en anglais, ce qui permet à des groupes de développeurs internationaux de travailler sur vos sources.

Si vous voulez ajouter manuellement de la documentation dans le fichier d'en-tête, ajoutez la documentation au-dessus de la méthode ou de la classe dans un commentaire de style C, avec la particularité que la première ligne doit commencer par une barre oblique (NdT : slash) suivie de deux astérisques.

Exemple :

  /** enables menuentries/toolbar items
        */
  void enableCommand(int id_);

10.3 Balises Spéciales

NOTE : La documentation suivante est tirée de la documentation fournie avec KDoc, écrite par Sirtaj S. Kang taj@.kde.org), l'auteur de KDoc ; Copyright (c) 1997

La documentation est composée de :

Les balises valides pour chaque type d'entité de code source sont :

Page suivante Page précédente Table des matières