Javadoc en Java

Documentez une méthode avec un commentaire spécial pour que les lecteurs et les outils voient ce qu’elle prend et ce qu’elle renvoie. Dans Yard.java, écrivez une méthode add qui prend int x et int y et renvoie leur somme. Placez un bloc /** */ directement au-dessus de add. Dans ce bloc, décrivez le travail en une phrase courte, puis balisez chaque paramètre avec @param et le résultat avec @return. Dans main, imprimez add(10, 2). Compilez avec javac Yard.java et lancez java Yard. L’écran doit montrer 12. Laissez les règles de naming pour la page suivante — cette leçon est la forme du commentaire de documentation, pas le choix des noms.

Placez /** au-dessus de la méthode

La page debugging a imprimé des valeurs pour trouver une mauvaise somme. Cette page écrit un commentaire de documentation au-dessus d’une méthode propre. Ouvrez Yard.java. Gardez le nom de classe public Yard. Supprimez les étiquettes println de debug restantes qui enterrent l’histoire de documentation, les démos equals / == restantes, les fichiers horn restants de Machine, et tout Scanner clavier. Le programme ne doit pas attendre la frappe. Aucune ligne import n’est requise pour cette démo.
Dans Yard, gardez une petite méthode et un court main. Le bloc de documentation doit siéger immédiatement au-dessus de la méthode qu’il décrit. Une ligne vide entre le */ de fermeture et la ligne de méthode convient. Ne cachez pas le bloc dans main. Ne placez pas le bloc sous le corps de la méthode.
Écrivez l’ouverture du commentaire avec deux étoiles après le slash :
/**
Puis écrivez une phrase simple qui dit ce que fait add. Puis écrivez les balises. Fermez avec :
*/
La méthode elle-même reste du Java ordinaire :
static int add(int x, int y) {
return x + y;
}
Javadoc ne change pas le fonctionnement de return. Il dit à un lecteur ce que la méthode promet avant qu’il lise chaque ligne du corps.

Depuis le dossier qui contient Yard.java, lancez javac Yard.java. Quand les parenthèses, accolades et points-virgules correspondent, javac n’écrit aucune ligne de son cru. Puis lancez java Yard — pas java Yard.java. Enlevez la fin .java de la commande d’exécution. Gardez une classe public dans le fichier pour que le nom corresponde à Yard.
L’écran montre 12. Parcourez l’exécution une fois. Java démarre à Yard.main. L’appel add(10, 2) entre dans la méthode avec x qui tient dix et y qui tient deux. La ligne return renvoie douze. System.out.println écrit ce nombre. Le bloc Javadoc n’imprime rien tout seul. Le bloc est pour les lecteurs et les outils de documentation. La preuve débutante de cette page reste une exécution correcte après un commentaire clair.
Lisez le bloc de commentaire en regardant la signature de la méthode. La phrase Adds two numbers. correspond au travail de return x + y;. La ligne @param x first number nomme le premier paramètre. La ligne @param y second number nomme le second paramètre. La ligne @return the sum of x and y nomme le résultat. Gardez l’orthographe exacte des balises : @param et @return utilisent le signe @ et des lettres latines.
Si vous voyez encore x=10 et y=2 puis 8 d’un fichier debugging, passez au fichier d’enseignement Javadoc et relancez java Yard. Si vous n’écrivez que // Adds two numbers. au-dessus de la méthode, vous avez écrit un commentaire de ligne ordinaire, pas un bloc Javadoc. Gardez la forme à double étoile /** pour que le bloc soit de la documentation, pas une note d’une seule ligne.
Dites la règle à voix haute en regardant l’écran : documentez au-dessus de la méthode, balisez les paramètres, balisez le retour, puis compilez et lancez pour prouver que la méthode fonctionne encore. N’inventez pas de longs cours de naming sur cette page. Le naming attend la leçon suivante.

Lisez la carte des balises

Un court tableau garde les trois pièces que vous avez tapées dans le commentaire. L’ouverture /** */ marque un bloc de documentation. @param décrit un nom de paramètre. @return décrit la valeur que la méthode renvoie. Gardez le nom de méthode add et l’appel add(10, 2) pour que l’écran reste un seul nombre clair.
Le tableau est la carte courte de cette page. D’abord vous placez le bloc. Puis vous balisez les entrées et la sortie. Puis vous vérifiez avec javac et java Yard. Évitez de deviner que tout style de commentaire est du Javadoc. Évitez de supprimer le bloc avant de savoir que le programme imprime encore 12.

Gardez le tableau à côté du fichier d’enseignement pendant que vous éditez. Pointez @param x dans le fichier, puis int x dans la signature. Pointez @param y, puis int y. Pointez @return, puis la ligne return. Ce jeu d’appariement est toute l’idée débutante en un passage. Les outils qui lisent Javadoc cherchent ces balises. Les lecteurs humains utilisent la même carte quand le corps de la méthode grandit plus tard.
Si des démos debugging restantes restent à côté, gardez-les comme histoire. Pour cette leçon, lancez le fichier d’enseignement Javadoc pour que l’écran montre 12 depuis add, pas des lignes étiquetées x= d’une chasse. Si javac se plaint de classes public en double, gardez seulement Yard public.

Un // ordinaire n’est pas du Javadoc

Une ligne qui commence par // est une note pour quelqu’un qui lit le fichier. Elle est utile, et ce cours a déjà utilisé des commentaires de ligne plus tôt. Ce n’est pas la forme de bloc de documentation que cette page enseigne. Javadoc pour une méthode commence par /** et se termine par */. Les balises @param et @return siègent à l’intérieur de ce bloc.
Si vous placez une chaîne ordinaire sous la méthode après d’autres instructions, cette chaîne n’est pas la documentation de la méthode. Le bloc de documentation doit être le commentaire attaché au-dessus de la méthode. Gardez le bloc serré contre add. Gardez main libre de théâtre de fausse documentation. L’appel dans main reste une impression normale de la somme renvoyée.
Quand le commentaire est faux mais le corps de la méthode est juste, javac peut encore réussir et java Yard peut encore imprimer 12. C’est pourquoi cette page vous demande de lire le commentaire et la signature ensemble, pas seulement l’écran. L’écran prouve le calcul. Le commentaire prouve que vous avez étiqueté le contrat.

Comparé aux impressions de debugging

Sur la page debugging, println répondait ce que vos nombres étaient vraiment quand une somme paraissait fausse. Sur cette page, Javadoc répond ce que add promet avant qu’un lecteur creuse dans le corps. Vous compilez encore Yard.java et lancez java Yard. Les nouveaux jetons sont /**, @param et @return au-dessus d’une méthode.
Debugging a utilisé une sortie ordinaire comme une lampe. Javadoc utilise un commentaire structuré comme une étiquette sur la porte de la méthode. Quand l’étiquette correspond aux paramètres et au retour, les lecteurs perdent moins de temps à deviner. Quand l’étiquette manque, le programme peut encore tourner — l’habitude de documentation manque encore.
Si un fichier debugging restant est encore ouvert, vous pouvez voir x=10, y=2 et une ancienne somme. Passez au fichier Javadoc pour que main imprime add(10, 2) et que la méthode porte le bloc de documentation. Gardez les cours de style de naming hors de cette page. Gardez la saisie clavier hors de cette page.

Avant le naming

Vous pouvez placer /** */ au-dessus de add, baliser @param x, baliser @param y, baliser @return, et voir encore 12 après java Yard. Compilez Yard.java et lancez java Yard pour la démo conservée. Le commentaire a dit le contrat aux lecteurs. La page suivante est le naming, où vous choisissez des noms clairs pour ce que vous écrivez.
Gardez la démo add documentée pour une paire claire commentaire-plus-exécution. Gardez les fichiers debugging hors de cette page quand vous pratiquez la documentation. Gardez les fichiers naming hors de cette page jusqu’à cette leçon. Ces trois habitudes sont le point de contrôle avant d’avancer. Quand les balises correspondent à la signature et que l’écran montre 12, Javadoc a fait son travail pour cette leçon et vous êtes prêt pour le sujet suivant sur le naming.
Un dernier passage dans le dossier : un Yard public, un add documenté, une impression dans main, pas d’attente clavier, pas de règles de naming forcées. Lancez javac Yard.java et java Yard une fois de plus sur la démo ouverte. Si l’écran montre encore 12 et que le commentaire siège encore au-dessus de add avec @param et @return, la forme de documentation est solide et le cours peut passer au naming à la page suivante. Préférez un seul bloc de documentation clair sur une méthode pour que chaque lecture enseigne la même carte.