L'environnement de bureau K

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_);