Deltakerne av Java-API-dokumentasjonen - dummies

Deltakerne dømt en gang for programmeringsspråk (inkludert Java) utelukkende av deres grammatiske trekk. Gjør en if-setning hva du forventer å gjøre? Er looping statements enkelt å bruke? Er metodene implementert effektivt?

I dag er ting litt annerledes. Java har en hel samling grammatiske funksjoner, men Java er mye mer enn bare et stort sett med grammatikkregler. Java har en standard Appl ication Programmeringsgrensesnitt - et stort bibliotek bestående av over 4 000 klasser, hver med egen funksjonalitet, egne begrensninger og egne regler for effektiv bruk.

Søker etter et begrep

Du kan finne ting i API-dokumentasjonen på en rekke forskjellige måter. Hver vei er praktisk i en situasjon eller en annen. For eksempel har Java en metode som heter System. ute. println. Det som følger beskriver to måter å slå opp systemet. ute. println metode.

Bruke indeksen

Slik finner du noe, for eksempel System. ute. println, ved hjelp av indeksen:

Besøk docs. orakel. com / javase / 8 / docs / API /.
Klikk på INDEX-koblingen øverst på siden for å åpne indeksen, som vist på figur 1.

Figur 1: API-dokumentasjonen er hovedsiden.
En liste over bokstaver er nær toppen av indeksen (se figur 2). Klikk på P-linken for å gå til delen med println i den.

“>
figur 2: API dokumentasjonens indeksside.
I P-delen, gjør et søk etter println for å finne println-oppføringene.

Med de fleste nettlesere kan du søke etter noe som println i teksten til en side. Slik gjør du det:
1. Pass på at nettleseren vet at du vil søke i den store rammen som tar opp det meste av siden (og ikke i de mindre rammene på venstre side av siden). For å gjøre dette, klikk musen inne i den store rammen. (Ikke klikk på en kobling. Klikk på noe nøytralt hvitt område i rammen.)
2. Åpne nettleserens Finn dialogboksen. På de fleste Windows-nettlesere, trykker Ctrl + F på dialogboksen Finn ut av skjul. På en Mac, klikker Command + F på trikset.
3. Når du ser dialogboksen Finn, skriv inn println i tekstboksen og klikk på boksen Finn eller Finn neste knapp.
Velg en av println-oppføringene.

P-delen har en stor båtlengde av println-oppføringer, som vist på figur 3 nedenfor. Oppføringene varierer fra hverandre på to måter:
- Hver oppføring sier println (int), println (String) eller println (someOtherTypeName). Typenavnet kan variere fra en oppføring til en annen.
- Hver oppføring sier at println er en metode i klassen java. somestuff. someMoreStuff . Klassen kan variere fra en oppføring til en annen.
  
  println oppføringer i API dokumentasjonens indeks. ">
  Figur 3: Noen println-oppføringer i API-dokumentasjonenes indeks.
På dette punktet lønner det seg å peke rundt. Hvis du prøver å skrive ut noe som "Hei verden! ", Vil du ha en av println (String) oppføringene. På den annen side, hvis du prøver å skrive ut verdien av lengdenOfStraightLine, vil du sannsynligvis velge en println (dobbel) oppføring.

Anta at du har bestemt deg for println (String). Du kan velge mellom tre println (String) oppføringer. En sier at det er en metode i klassen java. io. PrintStream, den neste er en metode i klassen java. io. PrintWriter, og den tredje er en metode i klassen java. sql. DriverManager. Hvilke av disse tre oppføringene velger du?

Vel, det du virkelig prøver å ringe er noe som heter System. ute. println. Hvis du går gjennom hele oppslaget rigmarole med Systemout, finner du det Systemet. ut har type PrintStream. (Se figur 4 nedenfor.) Så println (String) oppføringen du bestemmer deg for å velge, er

println (String) - Metode i klassen java. io. Print.

ut variabel har typen PrintStream. ">
Figur 4: Ut-variabelen har type PrintStream.
Klikk på linken for oppføringen du har valgt.

Når du klikker på koblingen println (String), tar nettleseren deg til en side som forklarer en println-metode, som vist i Figur 5. Siden viser deg hva println gjør ("Skriv ut en streng og deretter …") og peker på andre nyttige sider, som siden med dokumentasjonen for String.

println metode. ">
Figur 5: En beskrivelse av println-metoden.

Bruk listen over klasser

Slik finner du en oppføring i API-en ved å starte i listen over klasser:

Besøk docs. orakel. com / javase / 8 / docs / API /.
Finn siden som dokumenterer System-klassen.

Du leter etter dokumentasjon som forklarer System. ute. println. Så du ser opp System, jobber deg ut og derfra, jobber deg til println.

For å finne en lenke til System, se i den nederste rammen på venstre side av siden. (Se figur 6.) For tips om hvordan du finner tekst på siden, se trinn 3 i delen Bruke indeksen.

System klasse. ">
Figur 6: Finne en lenke til System-klassen.
Når du klikker på koblingen System, får du nettleseren til å vise dokumentasjonssiden for System-klassen, som vist i Figur 7.

Dokumentarkitektens dokumentasjon. “>
figur 7: Systemklassens dokumentasjon.
Finn ut variabelen på dokumentasjonssiden for systemklassen.

Hvis du bruker nettleserens Finn-dialogboks, må du klikke på Finn neste-knappen flere ganger. (Navnet er så vanlig, det vises flere ganger i flere sammenhenger på siden Systemdokumentasjon.) Når du har funnet det du leter etter, ser du et bord som det som vises i figur 4 ovenfor.
Klikk på PrintStream-lenken i tabellens utradisjon.

Ifølge dokumentasjonen refererer ut-variabelen til et objekt av typen PrintStream.Dette betyr at println er en del av PrintStream-klassen. Det er derfor du klikker på PrintStream-lenken.
På utskriftssiden for PrintStream finner du println (String).

Du ser en forklaring som den som er vist i Figur 5, ovenfor.

Du kan også gjøre det

Etter å ha fulgt trinnene i denne artikkelen, kan du bli fristet til å si "Big deal! Jeg kan finne println i API docs, men jeg finner sannsynligvis ikke noe annet. Og hvis folk lager dokumentasjon for ting de selv programmerer, så vil dokumentasjonen deres ikke se ut som standard API-dokumentasjon. Jeg kommer opp en bekk. "

Det rette svaret på en slik innsigelse er" Nonsens! Baloney! Vissvass! Hesterfjær! "Her er hvorfor:

De fleste triksene du trenger for å finne ting i standard Java-dokumentasjonen, er illustrert i denne artikkelen er trinnvise instruksjoner. Hvis du finner System. ute. println, du kan også finne javax. svinge. JButton eller noen av de 4, 200 programmene i standard Java API.

Og som du oppdager mer om Java og forholdene mellom klasser, metoder og variabler, vil denne artikkelen trinnvise instruksjoner føles mye mer naturlig.
Når du leser andres dokumentasjon, kan du klare det problemet rett utenfor listen din. Standard API-dokumenter ble ikke skrevet for hånd. De ble generert automatisk fra den aktuelle Java-programkoden. For eksempel koden for PrintStream. java har noen linjer som ser slik ut:
```
/ ** * Skriv ut en streng og avslutt deretter linjen. * Denne metoden fungerer som om den påberoper *

{@ link #print (String)}

* og deretter

{@ link #println ()}

. * * @param x Den

Strengen

skal skrives ut. * /
```
For å lage API-dokumentasjonen kjørte kapteinene på Java et program kalt javadoc . Javadoc-programmet tok linjer som disse rett ut av PrintStream. java-filen og brukte linjene til å gjøre dokumentasjonen du ser i nettleseren din.

Andre Java-programmerere gjør det samme. Faktisk bruker alle som skriver Java-kode javadoc-programmet til å generere dokumentasjon. Så allas Java-dokumentasjon ser ut som alle andre er Java-dokumentasjon. Når du vet hvordan du leser til standard API-dokumentasjonen, vet du hvordan du leser noens hjemmelagde Java-dokumenter.

Og ja, du kan bruke javadoc-programmet til å lage din egen dokumentasjon. Når du laster ned JDK, får du javadoc-programmet som en del av avtalen.