Donner un sens à la documentation de l'API de Java

Il était une fois, les personnes jugées langages de programmation (y compris Java) uniquement par leurs caractéristiques grammaticales. Est-ce une si

déclaration ce que vous attendez qu'il fasse? Sont des énoncés faciles à utiliser en boucle? Sont les méthodes mises en œuvre de manière efficace?

Aujourd'hui, les choses sont un peu différentes. Java a toute une collection de traits grammaticaux, mais Java est beaucoup plus que juste un grand ensemble de règles de grammaire. Java a une norme ApplInterface de programmation d'ication -une énorme bibliothèque composée de plus de 4000 classes, chacune avec sa propre fonctionnalité, ses propres limites et ses propres règles pour une utilisation efficace.

Recherche d'un terme

Vous pouvez trouver des choses dans la documentation de l'API dans un certain nombre de façons différentes. Chaque voie est pratique dans une situation ou d'une autre. Par exemple, Java a une méthode nommée System.out.println. Ce qui suit décrit deux façons de regarder le System.out.println Procédé.

Utilisation de l'indice

Voici comment faire pour trouver quelque chose, comme System.out.println, en utilisant l'index:

1. Visitez docs.oracle.com/javase/8/docs/api/.

2. Cliquez sur le lien INDEX en haut de la page pour ouvrir l'index, comme le montre la figure 1.

   
   Figure 1: La page principale du documentation de l'API.

   Une liste de lettres est près du haut de l'indice (voir la figure 2). Cliquez sur le lien P pour aller à la section avec println en elle.

   "/>
   Figure 2: La page d'index de la documentation de l'API.

3. Dans la section P, faire une recherche pour println pour trouver le println entrées.

   La plupart des navigateurs vous permettent de rechercher quelque chose comme println dans le texte d'une page. Voici comment:

1. Assurez-vous que le navigateur sait que vous voulez rechercher dans le grand cadre qui prend le plus de la page (et pas dans les cadres plus petits sur le côté gauche de la page). Pour ce faire, cliquez sur votre souris à l'intérieur du grand cadre. (Ne cliquez pas sur un lien. Cliquez sur une certaine zone blanche neutre de l'image.)

2. Ouvrez la boîte de dialogue de recherche du navigateur. Sur la plupart des navigateurs Windows, en appuyant sur Ctrl + F cajole la boîte de dialogue Rechercher sortir de la clandestinité. Sur un Mac, en cliquant sur Commande + F fait le tour.

3. Quand vous voyez la boîte de dialogue Rechercher, tapez println dans la zone de texte et cliquez sur la Recherche de la boîte ou le bouton Suivant.

Choisissez l'un des println entrées.

La section P a une grosse cargaison de println entrées, comme illustré sur la figure 3, ci-dessous. Les entrées diffèrent entre eux de deux façons:

Chaque entrée dit println (int), println (String), ou println (someOtherTypeName). Le nom du type peut différer d'une entrée à l'autre.

Chaque entrée indique que println est une méthode dans la classe java.someStuff.someMoreStuff. La classe peut différer d'une entrée à l'autre.

println entrées dans l'index de la documentation de l'API ". />

Figure 3: Certains println entrées dans l'index de la documentation de l'API.

À ce stade, il paye pour fouiner. Si vous essayez d'imprimer quelque chose comme "Bonjour le monde!", vous voulez un des println (String) entrées. D'autre part, si vous essayez d'imprimer la valeur de lengthOfStraightLine, vous aurez probablement de choisir un println (double) entrée.

Maintenant, supposons que vous avez décidé sur println (String). Vous pouvez choisir parmi trois println (String) entrées. On dit qu'elle est une méthode dans la classe java.io.PrintStream, l'autre est une méthode dans la classe java.io.PrintWriter, et la troisième est une méthode dans la classe java.sql.DriverManager. Lequel de ces trois entrées choisissez-vous?

Eh bien, ce que vous êtes vraiment essayer d'appeler quelque chose named System.out.println. Si vous passez par l'ensemble galimatias de recherche avec SystemOut, vous verrez que System.out a saisir PrintStream. (Voir la Figure 4 ci-dessous.) Ainsi, la println (String) entrée que vous décidez de choisir est

println (String) - Méthode dans java.io.PrintStream de classe.

Cliquez sur le lien pour l'entrée que vous avez choisi.

Lorsque vous cliquez sur le lien println (String), le navigateur vous emmène à une page qui explique un println méthode, comme le montre la Figure 5. La page vous indique ce que println ne ("Imprimer une chaîne, puis....") et des points à d'autres pages utiles, comme la page avec la documentation Chaîne.

méthode println. "/>

Figure 5: Une description de la println Procédé.

Utilisation de la liste des classes

Voici comment faire pour trouver une entrée dans l'API en commençant dans la liste des classes:

1. Visitez docs.oracle.com/javase/8/docs/api/.

2. Trouver la page qui documente le Système classe.

   Vous êtes à la recherche de documentation qui explique System.out.println. Alors vous regardez Système, travailler votre chemin vers dehors, et à partir de là, travailler votre chemin vers println.

   Pour trouver un lien vers Système, regarder dans le cadre inférieur sur le côté gauche de la page. (Voir Figure 6.) Pour des conseils sur la recherche de texte sur la page, voir l'étape 3 dans la section «Utilisation de l'indice".

   Classe System. "/>
   Figure 6: Trouver un lien vers le Système classe.

   En cliquant sur le lien Système rend votre navigateur affiche la page de documentation pour la Système classe, comme représenté sur la figure 7.

   La documentation de classe System. "/>
   Figure 7: Système la documentation de la classe.

3. Sur la page de documentation pour la Système classe, trouver le dehors variable.

   Si vous utilisez la boîte de dialogue Rechercher de votre navigateur Web, vous devez cliquer sur le bouton Suivant plusieurs fois. (Le nom dehors est si commun, il apparaît à plusieurs reprises dans différents contextes sur le Système page de documentation.) Lorsque vous avez trouvé ce que vous cherchez, vous voyez un tableau comme celui de la figure 4, ci-dessus.

4. Dans le tableau de dehors ligne, cliquez sur le lien PrintStream.

   Selon la documentation, le dehors variable fait référence à un objet de type PrintStream. Ceci veut dire cela println fait partie de la PrintStream classe. Voilà pourquoi vous en cliquant sur le PrintStream lien.

5. Sur la page de documentation pour PrintStream, trouver println (String).

   Vous voyez une explication comme celle montrée dans la Figure 5, ci-dessus.

Tu peux le faire aussi

Après avoir suivi les étapes de cet article, vous pouvez être tenté de dire, "Big deal! Je peux trouver println dans les docs de l'API, mais je ne peut probablement pas trouver autre chose. Et si les gens créent la documentation pour des trucs qu'ils programment sur leur propre, puis leur documentation ne ressemblera pas à la documentation de l'API standard. Je serai un ruisseau ".

La réponse appropriée à une telle objection est "Nonsense! Baloney! Balderdash! Plumes cheval!" Voici pourquoi:

• La plupart des trucs que vous avez besoin pour trouver des choses dans la documentation Java standard sont illustrés dans les instructions étape-par-étape de cet article. Si vous pouvez trouver System.out.println, vous pouvez également trouver javax.swing.JButton ou l'un des programmes 4200 de l'API standard Java.

  Et, comme vous le découvrirez plus sur Java et les relations entre les classes, les méthodes et les variables, les instructions étape-par-étape de cet article va se sentir beaucoup plus naturel.

• Quant à la lecture de la documentation d'autres personnes, vous pouvez rayer ce problème à droite de votre liste. Les docs de l'API standards ne sont pas tapés à la main. Ils ont été générées automatiquement à partir réelle code de programme Java. Par exemple, le code pour PrintStream.java a quelques lignes qui ressemblent à quelque chose comme ceci:

  / *** Imprimer une chaîne, puis terminer la ligne. * Cette méthode comporte comme si elle invoque *{#printlink (String)}*et alors {#printlnlink ()}.** @ param x La Chaîne à imprimer. * /

  Pour créer la documentation de l'API, les capitaines de Java couru un programme appelé javadoc. Le programme javadoc pris lignes comme celles-ci à droite de la PrintStream.java déposer et utilisé les lignes pour faire la documentation que vous voyez dans votre navigateur Web.

  Autres programmeurs Java font la même chose. En fait, tous ceux qui écrivent du code Java utilise le programme javadoc pour générer la documentation. Donc, la documentation Java de tout le monde ressemble à la documentation Java de tout le monde. Quand vous savez comment lire la documentation de l'API standard, vous savez lire Homegrown docs Java de personne.

  Et oui, vous pouvez utiliser le programme javadoc pour créer votre propre documentation. Lorsque vous téléchargez le JDK, vous obtenez le programme de javadoc dans le cadre de la transaction.