Dar sentido a la documentación de la API de Java

Érase una vez, las personas juzgadas lenguajes de programación (como Java) únicamente por sus características gramaticales. ¿Un si

Declaración de hacer lo que usted espera que haga? Están bucle declaraciones fáciles de usar? Son métodos implementados de manera eficiente?

Hoy en día, las cosas son un poco diferentes. Java tiene toda una colección de rasgos gramaticales, pero Java es mucho más que un gran conjunto de reglas gramaticales. Java tiene un estándar ApplInterfaz de programación de icación -una enorme biblioteca que consta de más de 4.000 clases, cada uno con su propia funcionalidad, sus propias limitaciones, y sus propias reglas para el uso efectivo.

Búsqueda de un término

Usted puede encontrar cosas en la documentación de la API en un número de maneras diferentes. Cada forma es conveniente en una u otra situación. Por ejemplo, Java dispone de un método denominado System.out.println. Lo que sigue describe dos maneras de ver el System.out.println método.

Utilizando el índice

Aquí es cómo encontrar algo, como System.out.println, utilizando el índice:

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

2. Haga clic en el enlace de índice en la parte superior de la página para abrir el índice, como se muestra en la Figura 1.

   
   Figura 1: Página principal de la documentación de la API.

   Una lista de letras está cerca de la parte superior del índice (véase la Figura 2). Haga clic en el enlace de P para ir a la sección con println en eso.

   "/>
   Figura 2: página de índice del documentación de la API.

3. En la sección P, hacer una búsqueda de println para encontrar la println entradas.

   La mayoría de los navegadores web que permiten buscar algo así como println en el texto de una página. Así es cómo:

1. Asegúrese de que el navegador sabe que desea buscar en el gran marco que ocupa la mayor parte de la página (y no en los marcos más pequeños en la parte izquierda de la página). Para ello, haga clic en el puntero del ratón dentro del gran marco. (No haga clic en un enlace. Haga clic en un área blanca neutra del marco.)

2. Abra la caja de diálogo Buscar del navegador. En la mayoría de los navegadores de Windows, al pulsar Ctrl + F engatusa el cuadro de diálogo Buscar salir de su escondite. En un Mac, clic Comando + F hace el truco.

3. Cuando vea el cuadro de diálogo Buscar, escriba println en el cuadro de texto y haga clic en Búsqueda de la caja o botón Buscar siguiente.

Escoja uno de los println entradas.

La sección de P tiene un gran cargamento de println entradas, como se muestra en la Figura 3, a continuación. Las entradas se diferencian entre sí de dos maneras:

Cada entrada dice println (int), println (String), o println (someOtherTypeName). El nombre del tipo puede diferir de una entrada a otra.

Cada entrada dice que println es un método en la clase java.someStuff.someMoreStuff. La clase puede diferir de una entrada a otra.

println entradas en el índice de la documentación de la API. "/>

Figura 3: Algunos println entradas en el índice de la documentación de la API.

En este punto, vale la pena hurgar. Si usted está tratando de imprimir algo así "¡Hola mundo!", Quieres uno de los println (String) entradas. Por otro lado, si usted está tratando de imprimir el valor de lengthOfStraightLine, es probable que elija una println (doble) de entrada.

Ahora, supongamos que usted haya decidido sobre println (String). Usted puede elegir entre tres println (String) entradas. Se dice que es un método en la clase java.io.PrintStream, el siguiente es un método en la clase java.io.PrintWriter, y el tercero es un método en la clase java.sql.DriverManager. ¿Cuál de estas tres entradas a elegir?

Bueno, lo que realmente está tratando de llamar es algo named System.out.println. Si usted va a través de todo el galimatías de búsqueda con SystemOut, usted encontrará que System.out ha escriba PrintStream. (Ver Figura 4, a continuación.) De modo que el println (String) entrada de decidirse a elegir es

println (String) - Método de la clase java.io.PrintStream.

Haga clic en el enlace para la entrada que usted ha elegido.

Al hacer clic en el enlace println (String), el navegador te lleva a una página que explica un println método, como se muestra en la Figura 5. La página que dice lo println no ("Imprimir una cadena y luego....") y apunta a otras páginas útiles, como la página con la documentación para Cuerda.

método println ". />

Figura 5: Una descripción de la println método.

Uso de la lista de clases

Aquí es cómo encontrar una entrada en la API, comenzando en la lista de clases:

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

2. Encuentra la página que documenta la Sistema clase.

   Usted está buscando documentación que explica System.out.println. Así que usted mira para arriba Sistema, su forma de trabajo a fuera, ya partir de ahí, su forma de trabajo a println.

   Para encontrar un enlace a Sistema, busque en el marco inferior en el lado izquierdo de la página. (Ver Figura 6.) Para consejos sobre cómo encontrar texto en la página, consulte el paso 3 en la sección "Uso del índice".

   Clase System ". />
   Figura 6: Encontrar un enlace a la Sistema clase.

   Al hacer clic en el enlace Sistema hace mostrar su navegador la página de documentación para el Sistema clase, como se muestra en la Figura 7.

   La documentación de la clase del sistema ". />
   Figura 7: El Sistema la documentación de la clase.

3. En la página de documentación de la Sistema clase, encontrar la fuera variable.

   Si utiliza cuadro de diálogo Buscar de su navegador web, lo que tienes que hacer clic en el botón Buscar siguiente varias veces. (El nombre fuera es tan común, que aparece varias veces en varios contextos diferentes en el Sistema página de documentación.) Cuando haya encontrado lo que estás buscando, usted ver una tabla como la que se muestra en la Figura 4, arriba.

4. En la tabla de fuera fila, haga clic en el enlace PrintStream.

   De acuerdo con la documentación, el fuera variable se refiere a un objeto de tipo PrintStream. Esto significa eso println es parte de la PrintStream clase. Es por eso que estás haciendo clic en el PrintStream enlace.

5. En la página de documentación PrintStream, encontrar println (String).

   Usted ve una explicación como la que se muestra en la Figura 5, arriba.

Puede hacerlo también

Después de seguir los pasos de este artículo, usted puede tener la tentación de decir: "Gran cosa! No puedo encontrar println en la documentación de la API, pero probablemente no puedo encontrar nada más. Y si la gente a crear documentación de cosas que programar por su cuenta, a continuación, su documentación no parecerse a la documentación de la API estándar. Subiré un arroyo ".

La respuesta adecuada a tal objeción es "¡Tonterías! Baloney! Balderdash! Plumas caballo!" He aquí por qué:

• La mayor parte de los trucos que necesitas para encontrar cosas en la documentación de Java estándar se ilustran en las instrucciones de este artículo paso a paso. Si usted puede encontrar System.out.println, también se puede encontrar javax.swing.JButton o cualquiera de los 4.200 programas de la API estándar de Java.

  Y, como a descubrir más acerca de Java y las relaciones entre las clases, métodos y variables, las instrucciones de este artículo paso a paso se sentirán mucho más natural.

• En cuanto a la lectura de la documentación de otras personas, puede rayar ese problema derecha de su lista. Los documentos de la API estándar no se escribieron con la mano. Se generan de forma automática a partir real código de programación Java. Por ejemplo, el código para PrintStream.java tiene unas líneas que se ven algo como esto:

  / *** Imprimir una cadena y luego terminar la línea. * Este método se comporta como si se invoca *{#printlink (String)}*y entonces {#printlnlink ()}.** @ param x La Cuerda a imprimir. * /

  Para crear la documentación de la API, los capitanes de Java corriendo un programa llamado javadoc. El programa javadoc tomó líneas como éstas directamente de la PrintStream.java presentar y usado las líneas para hacer la documentación que se ve en su navegador web.

  Otros programadores de Java hacen lo mismo. De hecho, todo el mundo que escribe código Java utiliza el programa javadoc para generar la documentación. Así documentación de Java de todo el mundo se parece a la documentación de Java de todos los demás. Cuando usted sabe cómo leer la documentación de la API estándar, ya sabes cómo leer cosecha propia documentación de Java de nadie.

  Y sí, puede utilizar el programa javadoc para crear su propia documentación. Al descargar el JDK, se obtiene el programa javadoc como parte del trato.