Page suivante Page précédente Table des matières
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
.
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.
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_);
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 :
<pre> .....morceaux de code.... </pre>
@nombalise [balise paramètres]
Les balises valides pour chaque type d'entité de code source sont :
@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
@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.
@see
comme ci-dessus
@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