Fazendo Sense of Java's API Documentation - dummies

Era uma vez que as pessoas julgaram linguagens de programação (incluindo Java) apenas por suas características gramaticais. Uma declaração if faz o que você espera que faça? As declarações de loop são fáceis de usar? Os métodos são implementados de forma eficiente?

Hoje em dia, as coisas são um pouco diferentes. O Java possui uma coleção completa de características gramaticais, mas Java é muito mais do que apenas um grande conjunto de regras de gramática. O Java possui uma interface de programação padrão Appl

Procurando um termo

Você pode encontrar coisas na documentação da API de várias maneiras diferentes. Cada maneira é conveniente em uma situação ou outra. Por exemplo, Java possui um método chamado System. Fora. println. O que se segue descreve duas maneiras de procurar o sistema. Fora. método println.

Usando o índice

Veja como encontrar algo, como o Sistema. Fora. println, usando o índice:

Visita docs. oráculo. com / javase / 8 / docs / api /.

Clique no link ÍNDICE na parte superior da página para abrir o índice, conforme mostrado na Figura 1.
Figura 1: a página principal da documentação da API.

Uma lista de letras está próxima da parte superior do índice (veja a Figura 2). Clique no link P para acessar a seção com println nela.
">

figura 2: a página de índice da documentação da API.
Na seção P, faça uma pesquisa para imprimir para encontrar as entradas println.
A maioria dos navegadores da Web permite que você procure por algo como println no texto de uma página. Veja como:

Certifique-se de que o navegador sabe que deseja pesquisar no quadro grande que ocupa a maior parte da página (e não nos quadros menores no lado esquerdo da página). Para fazer isso, clique no mouse dentro do quadro grande. (Não clique em um link. Clique em alguma área branca neutra do quadro.)
1. Abra a caixa de diálogo Localizar do navegador. Na maioria dos navegadores do Windows, pressionar Ctrl + F coaxia a caixa de diálogo Localizar fora de esconder. Em um Mac, clicar em Command + F faz o truque.
2. Quando você vê a caixa de diálogo Localizar, digite println na caixa de texto e clique no botão Procurar ou Procurar próximo da caixa.
3. Escolha uma das entradas println.
A seção P tem uma grande carga de carregamento de entradas de impressão, como mostrado na Figura 3, abaixo. As entradas diferem umas das outras de duas maneiras:

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. SomeSusff . A classe pode diferir de uma entrada para outra. imprimir as entradas no índice da documentação da API. ">
  
  Figura 3: Algumas entradas println no índice da documentação da API.
  Neste ponto, vale a pena picar. Se você está tentando imprimir algo como "Olá mundo! ", Você quer uma das entradas println (String). Por outro lado, se você estiver tentando imprimir o valor de lengthOfStraightLine, você provavelmente escolherá uma entrada println (double).
Agora, suponha que você tenha decidido em println (String). Você pode escolher entre três entradas println (String). Um diz que é um método na classe java. io. PrintStream, o próximo é um método na classe java. io. PrintWriter, e o terceiro é um método na classe java. sql. DriverManager. Qual dessas três entradas você escolheu?

Bem, o que você realmente está tentando chamar é algo denominado Sistema. Fora. println. Se você percorrer toda a pesquisa de rigmarole com Systemout, você encontrará esse Sistema. tem tipo PrintStream. (Veja a Figura 4, abaixo.) Então, a entrada println (String) que você decide escolher é

println (String) - Método na classe java. io. PrintStream. A variável

out tem o tipo PrintStream. ">

Figura 4: A variável out tem o tipo PrintStream.
Clique no link para a entrada que você escolheu.
Quando você clica no link println (String), o navegador leva você a uma página que explica um método println, como mostrado na Figura 5. A página informa o que println faz ("Print a String and then …") e aponta para outras páginas úteis, como a página com a documentação para String.

println method. ">

Figura 5: Uma descrição do método println.
Usando a lista de classes

Veja como encontrar uma entrada na API começando na lista de classes:

Visita docs. oráculo. com / javase / 8 / docs / api /.

Encontre a página que documenta a classe System.
Você está procurando uma documentação que explique o Sistema. Fora. println. Então, você olha para o Sistema, trabalhe para sair e, a partir daí, trabalhe seu caminho para imprimir.

Para encontrar um link para o sistema, veja o quadro inferior no lado esquerdo da página. (Consulte a Figura 6.) Para obter dicas sobre como encontrar texto na página, consulte o Passo 3 na seção "Usando o índice".

Classe do sistema. ">
Figura 6: Encontrar um link para a classe System.
Ao clicar no link Sistema, seu navegador exibe a página de documentação para a classe System, conforme mostrado na Figura 7.
Documentação da classe do sistema. ">

figura 7: documentação da classe do sistema.
Na página de documentação para a classe System, encontre a variável out.
Se você usar a caixa de diálogo Procurar do seu navegador, você deve clicar no botão Localizar próximo várias vezes. (O nome é tão comum, aparece várias vezes em vários contextos diferentes na página de documentação do Sistema.) Quando você encontrou o que está procurando, você vê uma tabela como a mostrada na Figura 4 acima.

Na linha de saída da tabela, clique no link PrintStream.
De acordo com a documentação, a variável out se refere a um objeto do tipo PrintStream.Isso significa que println faz parte da classe PrintStream. É por isso que você está clicando no link PrintStream.

Na página de documentação do PrintStream, encontre println (String).
Você vê uma explicação como a mostrada na Figura 5, acima.

Você também pode fazê-lo

Depois de seguir as etapas deste artigo, você pode ficar tentado a dizer: "Grande coisa! Posso encontrar println nos documentos do API, mas provavelmente não consigo encontrar mais nada. E se as pessoas criam documentação para coisas que eles programam por conta própria, sua documentação não parecerá a documentação da API padrão. Eu irei até um riacho. "

A resposta apropriada a essa objeção é" absurdo! Baloney! Balderdash! Penas de cavalo! "Aqui está o motivo:

A maioria dos truques que você precisa para encontrar coisas na documentação Java padrão são ilustrados nas instruções passo a passo deste artigo. Se você pode encontrar o Sistema. Fora. println, você também pode encontrar o javax. balanço. JButton ou qualquer um dos programas 4, 200 na API Java padrão.

E, à medida que você descobre mais sobre Java e as relações entre classes, métodos e variáveis, as instruções passo a passo deste artigo se sentirão muito mais naturais.

Quanto à leitura da documentação de outras pessoas, você pode arranhar esse problema diretamente da sua lista. Os documentos API padrão não foram digitados à mão. Eles foram gerados automaticamente a partir do código real do programa Java. Por exemplo, o código para PrintStream. java tem algumas linhas que se parecem com isto:
/ ** * Imprima uma String e, em seguida, termine a linha. * Este método se comporta como se invocasse *
```
{@ link #print (String)}

* e depois

{@ link #println ()}

. * * @param x A

String

a ser impressa. * /

Para criar a documentação da API, os capitães do Java executaram um programa chamado
```
javadoc . O programa javadoc levou linhas como esta diretamente do PrintStream. arquivo java e usou as linhas para fazer a documentação que você vê em seu navegador. Outros programadores Java fazem o mesmo. Na verdade, todos os que escrevem código Java usam o programa javadoc para gerar documentação. Assim, a documentação de todos em Java é a documentação Java de todos os outros. Quando você sabe como lê a documentação da API padrão, você sabe como ler os documentos Java de todos os paises.

E sim, você pode usar o programa javadoc para criar sua própria documentação. Quando você baixa o JDK, você obtém o programa javadoc como parte do negócio.