Making Sense de Documentação da API do Java

Era uma vez, as pessoas julgadas linguagens de programação (incluindo Java) unicamente por suas características gramaticais. faz um E se

declaração não o que você espera que ele faça? São looping declarações fácil de usar? Os métodos são implementados de forma eficiente?

Hoje em dia, as coisas são um pouco diferentes. Java tem toda uma coleção de características gramaticais, mas Java é muito mais do que apenas um grande conjunto de regras gramaticais. Java tem um padrão ApplInterface de Programação de icação -uma enorme biblioteca que consiste em mais de 4.000 classes, cada um com sua própria funcionalidade, suas próprias limitações, e as suas próprias regras para o uso efetivo.

Procurar um termo

Você pode encontrar coisas na documentação da API em um número de maneiras diferentes. Cada forma é conveniente em uma situação ou outra. Por exemplo, Java tem um método denominado System.out.println. O que se segue descreve duas maneiras de olhar o System.out.println método.

Utilizando o índice

Veja como encontrar algo, como System.out.println, usando o índice:

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

2. Clique no link INDEX no topo da página para abrir o índice, como mostrado na Figura 1.

   
   Figura 1: A página principal do documentação da API.

   Uma lista de cartas está perto do topo do índice (ver Figura 2). Clique no link P para ir para a seção com println nisso.

   "/>
   Figura 2: índice página de Documentação da API.

3. Na seção P, fazer uma pesquisa para println para encontrar o println entradas.

   A maioria dos navegadores permitem que você procure por algo como println no texto de uma página. Veja como:

1. Verifique se o navegador sabe que você deseja pesquisar na grande quadro que ocupa a maior parte da página (e não nos quadros menores no lado esquerdo da página). Para fazer isso, clique com o mouse dentro do grande quadro. (Não clique em um link. Clique em alguma área branca neutra do quadro.)

2. Abra a caixa de diálogo Localizar do navegador. Na maioria dos navegadores do Windows, pressionando Ctrl + F persuade a caixa de diálogo Find sair do esconderijo. Em um Mac, clicando em Command + F faz o truque.

3. Quando você vê a caixa de diálogo Localizar, digite println na caixa de texto e clique em Find do caixa ou botão Localizar próxima.

Escolha um dos println entradas.

A seção P tem um grande barco cheio de println entrada, como mostrado na Figura 3, abaixo. As entradas diferem uma da outra em duas formas:

Cada entrada diz println (int), println (String), ou println (someOtherTypeName). O nome do tipo pode diferir de uma entrada para outra.

Cada entrada diz que println é um método na classe Java.someStuff.someMoreStuff. A classe podem diferir de uma entrada para outra.

entradas println no índice da documentação da API ". />

Figura 3: Alguns println entradas no índice da documentação da API.

Neste ponto, vale a pena fuçar. Se você está tentando imprimir algo como "Olá Mundo!", você quer um dos println (String) entradas. Por outro lado, se você está tentando imprimir o valor de lengthOfStraightLine, você provavelmente vai escolher um println (duplo) entrada.

Agora, suponha que você tenha decidido sobre println (String). Você pode escolher entre três println (String) entradas. Um diz que é um método em sala de aula java.io.PrintStream, a seguir é um método na classe java.io.PrintWriter,e o terceiro é um método na classe java.sql.DriverManager. Qual destes três entradas que você escolhe?

Bem, o que você está realmente tentando chamar é algo nomeados System.out.println. Se você passar por toda a ladainha de pesquisa com SystemOut, você vai descobrir que System.out tem o tipo PrintStream. (Veja a Figura 4, abaixo.) Assim, o println (String) entrada que você decidir escolher é

println (String) - Método na java.io.PrintStream classe.

Clique no link para a entrada que você escolheu.

Quando você clica no link de println (String), o navegador leva você a uma página que explica a println método, como mostrado na Figura 5. A página diz-lhe que println O ( "Imprimir uma String e então....") e aponta para outras páginas úteis, como a página com a documentação Corda.

método println ". />

Figura 5: A descrição do println método.

Usando a lista de classes

Aqui é como encontrar uma entrada na API, iniciando na lista de classes:

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

2. Encontrar a página que documenta o Sistema classe.

   Você está procurando documentação que explica System.out.println. Então você olha para cima Sistema, sua maneira de trabalhar Fora, e de lá, sua maneira de trabalhar println.

   Para encontrar um link para Sistema, olhar no quadro inferior do lado esquerdo da página. (Veja a Figura 6.) Para obter dicas sobre como encontrar texto na página, consulte a Etapa 3 em "Utilizar o índice" seção.

   classe do sistema. "/>
   Figura 6: Encontrar um link para o Sistema classe.

   Ao clicar no link do sistema faz com que o navegador exibir a página de documentação para o Sistema classe, como mostrado na Figura 7.

   documentação da classe System ". />
   Figura 7: A Sistema documentação da classe.

3. Na página de documentação para o Sistema classe, encontrar o Fora variável.

   Se você usar a caixa de diálogo Localizar do seu navegador, você tem que clicar no botão Localizar próxima várias vezes. (O nome Fora é tão comum, que aparece várias vezes em vários contextos diferentes no Sistema página de documentação.) Quando você encontrar o que você está procurando, você ver uma tabela como a mostrada na Figura 4, acima.

4. Na tabela de Fora linha, clique no link PrintStream.

   De acordo com a documentação, o Fora variável refere-se a um objeto do tipo PrintStream. Isso significa que println faz parte da PrintStream classe. É por isso que você está clicando no PrintStream ligação.

5. Na página documentação para PrintStream, encontrar println (String).

   Aparece uma explicação como a mostrada na Figura 5, acima.

Você pode fazê-lo também

Depois de seguir os passos descritos neste artigo, você pode ser tentado a dizer: "Grande coisa! Posso encontrar println na documentação de API, mas eu provavelmente não pode encontrar qualquer outra coisa. E se as pessoas a criar documentação para coisas que eles programar por conta própria, em seguida, sua documentação não vai olhar como a documentação da API padrão. Eu vou ser até um riacho ".

A resposta adequada a tal objeção é "Nonsense! Baloney! Balderdash! Penas do cavalo!" Aqui está o porquê:

• A maioria dos truques que você precisa para encontrar coisas na documentação Java padrão são ilustrados na instruções passo-a-passo deste artigo. Se você pode encontrar System.out.println, você também pode encontrar javax.swing.JButton ou qualquer um dos programas 4.200 na API Java padrão.

  E, como você descobrir mais sobre Java e as relações entre as classes, métodos e variáveis, instruções passo-a-passo deste artigo vai se sentir muito mais natural.

• Como para ler a documentação de outras pessoas, você pode riscar esse problema direito fora de sua lista. A documentação de API padrão não foram digitados manualmente. Eles foram gerados automaticamente a partir do código real programa de Java. Por exemplo, o código PrintStream.java tem algumas linhas que algo parecido com isto:

  / *** Imprimir uma String e em seguida, encerrar a linha. * Este método se comporta como se ele invoca *{#print @link (String)}*e depois {#println @link ()}.** @ Param x A Corda para ser impresso. * /

  Para criar a documentação da API, os chefes de Java correu um programa chamado javadoc. O programa javadoc tomou linhas como estes direita fora da PrintStream.java arquivo e usado as linhas para fazer a documentação que você vê no seu navegador web.

  Outros programadores Java fazer a mesma coisa. Na verdade, todo mundo que escreve código Java usa o programa javadoc para gerar documentação. Então documentação Java de todos parece documentação Java de todo mundo. Quando você sabe como ler a documentação da API padrão, você sabe como ler caseiros docs Java de ninguém.

  E sim, você pode usar o programa javadoc para criar sua própria documentação. Quando você baixar o JDK, você começa o programa javadoc como parte do negócio.