Le Manuel de Programmation de KDevelop: Documentation de Classe avec KDoc

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 :

- Texte normal. Les paragraphes doivent être séparés par au moins une ligne vide.
- Texte de la forme

      <pre>
      .....morceaux de code....
      </pre>

- Différentes balises de la forme :

  > `

  >     @nombalise [balise paramètres]

  > `

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

- Classes

  > `

  >       @short [une phrase de texte]
  >             Une description brève de la classe
  >       @author [une phrase de texte]
  >             Auteur de la classe
  >       @version [une phrase de texte]
  >             Version de la classe (Généralement, j'utilise la valeur "Id" de RCS/CVS)
  >       @see [une ou plusieurs références à des classes ou méthodes]
  >             Références à d'autres documentations

  > `

- Méthodes

  > `

  >       @see
  >             comme ci-dessus
  >       @return [une phrase]
  >             Une phrase décrivant la valeur de retour
  >       @param [paramètre nom identificateur] [paramètre description]
  >             Décrit un paramètre. La description du paramètre peut utiliser
  >             plusieurs lignes et se termine par une ligne vide, la fin du
  >             commentaire, ou une autre entrée de paramètre. Pour cette raison,
  >             les entrées de paramètre devraient être la fin du commentaire.

  > `

- Constantes, Énumérations, Propriétés

  > `

  >       @see
  >             comme ci-dessus

  > `

- Voir aussi `@ref` Contrairement au format javadoc, la méta-balise "@ref" a le même format que @see mais peut être utilisée n'importe où dans la documentation (toutes les autres balises doivent apparaître sur des lignes différentes).

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