Comment utiliser javadoc pour documenter vos classes

Une étape reste avant que vous pouvez rendre publique votre bibliothèque de classe nouvelle chaude ou de l'application: la préparation de la documentation pour ses classes. Heureusement, Java fournit un outil appelé JavaDoc

Sommaire

  • qui peut automatiquement créer des documents au format HTML de fantaisie sur la base des commentaires dans vos fichiers source.

    Tout ce que vous avez à faire est d'ajouter un commentaire à chaque classe publique, sur le terrain, et méthodologiques puis exécutez les fichiers source à travers le javadoc commandement voil # 225-! vous avez de la documentation d'aspect professionnel, basé sur le Web pour vos classes.

    Ajout de commentaires JavaDoc

    La règle de base pour la création de commentaires JavaDoc est qu'ils commencent par / ** et finir avec * /. Vous pouvez placer des commentaires JavaDoc dans l'un des trois endroits différents dans un fichier source:

    • Immédiatement avant la déclaration d'une classe publique

    • Immédiatement avant la déclaration d'un champ public

    • Immédiatement avant la déclaration d'une méthode ou d'un constructeur publique

    Un commentaire Javadoc peut inclure du texte qui décrit la classe, sur le terrain, ou de la méthode. Chaque ligne suivante d'un commentaire Javadoc multiligne commence habituellement par un astérisque. JavaDoc ignore ce astérisque et tout espace blanc entre elle et le premier mot de la ligne.

    Le texte dans un commentaire JavaDoc peut inclure des balises HTML si vous voulez appliquer la mise en forme de fantaisie. Vous devriez éviter d'utiliser des balises de titre (

    et ainsi de suite), car ceux JavaDoc crée et vos balises de titre vient compliquer les choses. Mais vous pouvez utiliser des balises pour gras et en italique ( et ) Ou pour formater des exemples de code (utilisez le
    tag).

    En outre, vous pouvez inclure spéciale doc tags qui fournissent des informations spécifique utilisé par JavaDoc pour formater les pages de documentation.

    BaliseExplication
    authorFournit des informations sur l'auteur, généralement le nom de theauthor, adresse e-mail, site web des informations, et bientôt.
    versionIndique le numéro de version.
    @depuisUtilisé pour indiquer la version avec laquelle on a ajouté cette classe, sur le terrain, ormethod.
    paramFournit le nom et la description d'une méthode orconstructor.
    returnFournit une description de la valeur de retour d'une méthode.
    throwsIndique exceptions qui sont jetés par une méthode orconstructor.
    deprecatedIndique que la classe, un champ ou méthode est déconseillée andshouldn't être utilisés.

    Pour vous donner une idée de la façon dont les commentaires Javadoc sont généralement utilisés, vérifier ce code.

    Notez que pour le Employé classe de compiler, vous devez également fournir une classe nommée Adresse, ce qui représente une adresse de rue. La classe simple suivante suffira:

    Adresse publique classe implémente Cloneable {String public String de la rue publique ville-public String public-état cordes zipCode-}

    Ce code montre une classe d'employés avec des commentaires JavaDoc.


    forfait com.lowewriter.payroll - / ** * Représente un employéauthor Doug Lowe *author LoweWriter.com *version 1.5 * 1.0 *since / Employé public class {private String lastName-privé Double salaire cordes firstName-privé. - / ** Représente l'adresse de l'employé * / adresse Adresse publique -.. / ** Crée un employé avec le nom spécifié *param NOM nom de l'employé *param Prénom Le prénom de l'employé * / Employé publique (String.. lastName, String prenom) {this.lastName = lastName-this.firstName = prenom-this.address = nouvelle adresse () -} / ** Obtient le nom de l'employé *return Une chaîne représentant dernière * nom de l'employé *.. / public String getLastName () {return this.lastName -} / ** Définit le nom de l'employé *param NOM * Une chaîne contenant le nom de l'employé * / setLastName public void (String nom) {this.lastName = lastName.. -..} / ** Obtient le prénom de l'employé *return Une chaîne représentant la première * nom * / public String getFirstName de l'employé () {return this.firstName -} / ** Définit le prénom de l'employé *param firstName. Une chaîne contenant le * Prénom de l'employé * / public void setFirstName (String prenom) {this.firstName = prenom -}... / ** Obtient le salaire de l'employé *return Un double représentant le salaire de l'employé * / public à double getSalary ( ) {return this.salary -} / ** Définit le salaire de l'employé *param nomFamille Un double * contenant le salaire de l'employé * / setSalary public void (double salaire) {this.salary = salary-}}..

    Utilisation de la commande javadoc

    La javadoc commande a quelques dizaines d'options que vous pouvez définir, ce qui en fait une commande compliqué à utiliser. Toutefois, vous pouvez ignorer toutes ces options pour créer un ensemble de base des pages de documentation. Il suffit de spécifier le chemin complet à tous les fichiers Java que vous souhaitez créer une documentation pour, comme ceci:

    javadoc com  lowewriter  paie  *. java

    La javadoc commande crée les pages de documentation dans le répertoire courant, de sorte que vous voudrez peut-être changer le répertoire dans lequel vous voulez que les pages de résider en premier.

    Pour plus d'informations sur l'utilisation de cette commande, reportez-vous à la documentation javadoc sur le site Web du Soleil.

    Affichage des pages JavaDoc

    Après vous exécutez la commande javadoc, vous pouvez accéder aux pages de documentation en commençant par la page index.html. Pour afficher rapidement cette page, il suffit de taper index.html à l'invite de commande après vous exécutez la commande javadoc. Ou vous pouvez commencer votre navigateur, accédez au répertoire où vous avez créé les pages de documentation, et ouvrez la page index.html.

    image0.jpg

    Si vous pensez que cette page semble familier, qui est parce que la documentation de l'API Java a été créée en utilisant JavaDocs. Donc, vous devriez déjà savoir comment trouver votre chemin autour de ces pages.

    Pour consulter la documentation pour une classe, cliquez sur le lien du nom de la classe. Une page avec une documentation complète pour la classe se lève. JavaDocs généré cette page à partir du fichier source.

    image1.jpg

    » » » » Comment utiliser javadoc pour documenter vos classes