Sites


KDE guide de développement

Documentation

Documentation

Si vous écrivez de nouvelles fonctions pour un projet KDE, nous espérons certainement que vous rédigerez de la documentation (apidox) pour celles-ci et essaierez d'expliquer aussi clairement que possible ce qu'on peut faire avec les fonctions. Mieux vous documenterez votre travail, plus les développeurs seront susceptibles de l'utiliser et moins ils risqueront de vous ennuyer en posant des questions de base sur son fonctionnement.

La documentation de l'API est parfois appelée « Manuel de référence des API ». Ce ne doit pas être un simple manuel de référence, cependant. Elle peut contenir quantité d'éléments additionnels, tels que tutoriels, des exemples et des informations historiques. Cette page fait référence à tout le matériau qui documente et explique l'API d'un morceau de code en tant que « apidox », le terme utilisé dans la documentation de la plate-forme de développement de KDE elle-même.

Écrire des « apidox » de base est amusant et simple : ajoutez des commentaires spécialement mis en forme dans votre code, expliquant ce que les choses sont censées être. Ces commentaires étant presque impossibles à distinguer de ce que vous écririez dans les en-têtes de votre code de toute façon, ce n'est pas difficile à faire. Voici un échantillon.

 
/**
 * @author praxagora
 *
 * Retourne un χ² comparant deux échantillons.
 * Les tableaux doivent être de la même taille.
 *
 * @param a Premier échantillon
 * @param b Second échantillon
 *
 * @return @size taille de chaque échantillon.
 */ 
double chi_square(double a[], double b[], int size) { 
double total_a=0.0, total_b=0.0, total, totals[size],
square_a[size], square_b[size], square_totals[size],
    terms[size],
    terms_total=0.0, sum_total=0.0, square_sum_total=0.0;
  int i;
  /**
    * Cette boucle comprend la fonction complète et calcule
    * le χ² à partir des deux tableaux.
  */
    { 
  for (i = 0; i < size ; i++)

Notez qu'un commentaire a été inclus avant la fonction, et avant l'accolade qui débute le niveau d'imbrication suivant, une boucle « for ». Tous les paramètres, ainsi que la valeur de retour, sont marqués.

Pour écrire une bonne « apidox », il faut d'abord des connaissances techniques : vous devez comprendre le code que vous documentez -- ou au moins savoir ce qu'il est censé faire et comment il est destiné à être utilisé. L'autre partie d'une bonne « apidox » relève de la discipline pure : les « apidox » sont les plus utiles lorsqu'elles sont exhaustives.

En fait, la documentation n'a habituellement pas à expliquer ce que fait le code à chaque étape. Le code devra être si clair, avec une disposition propre et des noms bien choisis pour les méthodes et les variables, qu'il s'auto-documentera. À la place, la documentation devra expliquer à quoi le code est destiné, quand et pourquoi il est appelé, les objectifs et les intervalles de ses arguments, voire peut-être l'algorithme utilisé sans oublier les compromis consentis en termes de temps et de mémoire.

Consultez la documentation de Qt pour vous faire une impression de ce à quoi doivent ressembler de bonnes « apidox ». Elles présentent une cohérence de style et sont imprégnées d'un souci d'exhaustivité. Vous pouvez en apprendre beaucoup sur Qt juste en lisant la documentation. Vous n'avez pas nécessairement besoin d'exécuter les programmes tutoriels ou de lire le code source de la bibliothèque pour découvrir ce que fait un paramètre ou un drapeau dans une certaine méthode de la bibliothèque. Elle vous est entièrement expliquée dans le détail.

Il y a une erreur de communication avec le serveur Booktype. Nous ne savons pas actuellement où est le problème.

Vous devriez rafraîchir la page.