Share
Cette petite leçon couvre Javadoc, un outil utile pour générer de la documentation à partir de vos fichiers source Java. Cette leçon fait partie d'une série de didacticiels en cours destinés aux développeurs apprenant Java afin de développer des applications Android..
Javadoc est un utilitaire fourni avec le SDK Java qui permet aux développeurs de générer une documentation de code à partir de fichiers source Java. Les environnements de développement tels qu'Eclipse prennent en charge Javadoc et peuvent générer des matériaux de référence HTML interrogeables à partir de commentaires de type Javadoc. En fait, la référence du SDK Android est une forme de documentation Javadoc..
La documentation Javadoc utilise une combinaison de traitement du code source (et de types d'inspection, de paramètres, etc.) et de lecture des balises de commentaire spéciales fournies par le développeur en tant que métadonnées associées à une section de code..
Un commentaire de style Javadoc doit précéder le code auquel il est associé. Par exemple, un commentaire Javadoc pour une classe doit être juste au-dessus de la déclaration de la classe et un commentaire pour une méthode doit être juste au-dessus de la déclaration de la méthode. Chaque commentaire doit commencer par une brève description, suivie d'une option plus longue. Vous pouvez ensuite inclure un certain nombre de balises de métadonnées différentes, qui doivent être fournies dans un ordre spécifique. Certaines balises importantes comprennent:
Vous pouvez également créer vos propres balises personnalisées à utiliser dans la documentation..
Pendant que vous écrivez du code dans Eclipse, vous pouvez générer un commentaire de style Javadoc en sélectionnant l’élément à commenter (nom de classe, nom de méthode, etc.) et en appuyant sur Alt-Shift-J Mac). Cela créera un commentaire de style Javadoc de base pour vous permettre de remplir les détails.
Regardons un exemple. Voici un simple commentaire Javadoc décrivant une classe:
/ ** * Activité de chargement des ressources de structure * * Cette activité permet d'afficher différentes ressources de structure pour un tutoriel sur la conception d'interface utilisateur. * * @author LED * @version 2010.1105 * @since 1.0 * / public class LayoutActivity étend l'activité
Voici à quoi cela ressemblera lorsque vous générerez la documentation Javadoc:
Regardons un exemple. Voici un simple commentaire Javadoc décrivant un champ dans une classe:
/ ** * Balise de débogage à utiliser pour la journalisation de la sortie de débogage dans LogCat * / private static final String DEBUG_TAG = "MyActivityDebugTag";
Voici à quoi cela ressemblera lorsque vous générerez la documentation Javadoc:
Examinons maintenant deux exemples de commentaires de méthode. Voici un simple commentaire Javadoc décrivant une méthode dans une classe:
/ ** * Méthode qui ajoute deux entiers ensemble * * @param a Le premier entier à ajouter * @param b Le deuxième entier à ajouter * @return La somme résultante de a et b * / public int addIntegers (int ) retour (a + b);
Maintenant, regardons une méthode qui retourne void, mais lève une exception:
/ ** * Cette méthode lève simplement une exception si le paramètre entrant a n'est pas un nombre positif, juste pour le plaisir. * * @param a S'il faut ou non lever une exception * @throws Exception * / public void throwException (boolean shouldThrow) lève Exception if (shouldThrow == true) lance new Exception ();
Voici à quoi cela ressemblera lorsque vous générerez la documentation Javadoc pour ces deux méthodes:
Pour générer la documentation de code Javadoc dans Eclipse, accédez au menu Projet et choisissez l’option «Générer Javadoc…». Ceci lancera un assistant qui vous permettra de choisir les projets pour générer de la documentation pour.
Depuis cet assistant, vous devez pointer Eclipse sur l'outil de ligne de commande javadoc.exe approprié (vous le trouverez dans le répertoire / bin de votre JDK). Vous pouvez également configurer certains paramètres de la documentation, par exemple pour documenter tout le code ou uniquement les classes visibles, les membres, etc. Enfin, choisissez une destination pour vos fichiers de documentation..
Même sans générer les fichiers Javadoc, Eclipse affiche la documentation de style Javadoc lorsque vous survolez vos méthodes, etc., comme illustré dans la figure ci-dessous..
Pour en savoir plus, consultez la référence Javadoc sur le site Web Oracle. Une FAQ Javadoc utile est également disponible..
Dans cette rapide leçon, vous avez appris à propos de Javadoc, un outil puissant utilisé par les développeurs Java pour documenter en profondeur le code source à des fins de référence et de maintenance. Eclipse, l’environnement de développement utilisé par de nombreux développeurs Android, prend en charge de manière intégrée Javadoc..
Les développeurs mobiles Lauren Darcey et Shane Conder ont co-écrit plusieurs livres sur le développement Android: un livre de programmation en profondeur intitulé Développement d'applications sans fil Android et Sams TeachYourself Développement d'applications Android en 24 heures. Lorsqu'ils n'écrivent pas, ils passent leur temps à développer des logiciels mobiles dans leur entreprise et à fournir des services de conseil. Vous pouvez les contacter par courrier électronique à l'adresse [email protected], via leur blog à l'adresse androidbook.blogspot.com et sur Twitter @androidwireless..
Accentsconagua