Dømme enkeltvis programmeringssprog (inklusive Java) udelukkende ved at gøre Sense of Javas API-dokumentation - dummies

Deltagerne dømte engang programmeringssprog (inklusive Java) udelukkende af deres grammatiske egenskaber. Gør en if-erklæring hvad du forventer at gøre? Er looping erklæringer nemme at bruge? Er metoder implementeret effektivt?

I dag er tingene lidt anderledes. Java har en hel samling af grammatiske funktioner, men Java er meget mere end blot et stort sæt grammatikregler. Java har en standard Appl ication Programmeringsgrænseflade - et stort bibliotek bestående af over 4, 000 klasser, hver med egen funktionalitet, egne begrænsninger og egne regler for effektiv brug.

Søger efter et udtryk

Du kan finde ting i API dokumentationen på en række forskellige måder. Hver vej er praktisk i en situation eller en anden. For eksempel har Java en metode kaldet System. ud. println. Det følgende beskriver to måder at kigge op på systemet. ud. println metode.

Brug af indekset

Sådan finder du noget, som System. ud. println ved at bruge indekset:

1. Besøg docs. Oracle. dk / javase / 8 / docs / api /.

2. Klik på INDEKS-linket øverst på siden for at åbne indekset, som vist i figur 1.

   

   Figur 1: API-dokumentationens hovedside.

   En liste over bogstaver er tæt på toppen af ​​indekset (se figur 2). Klik på P-linket for at gå til sektionen med println i den.

   

   ”>
   figur 2: API dokumentationens indeksside.

3. I sektionen P skal du søge efter println for at finde println-posterne.

   De fleste webbrowsere giver dig mulighed for at søge efter noget som println i teksten på en side. Sådan gør du:

   1. Sørg for, at browseren ved, at du vil søge i den store ramme, der optager det meste af siden (og ikke i de mindre rammer på venstre side af siden). For at gøre dette skal du klikke på musen inde i den store ramme. (Klik ikke på et link. Klik på noget neutralt hvidt område i rammen.)

   2. Åbn browserens Find dialogboks. På de fleste Windows-browsere trykker Ctrl + F sammen i dialogboksen Find uden at gemme sig. På en Mac, klikker Command + F på tricket.

   3. Når du ser dialogboksen Søg, skal du skrive println i tekstfeltet og klikke på boksens Find eller Find Next-knap.

4. Vælg en af ​​println-posterne.

   P-sektionen har en stor boatload af println-indgange, som vist i figur 3 nedenfor. Posterne adskiller sig fra hinanden på to måder:

   • Hver post siger println (int), println (String) eller println (someOtherTypeName). Typenavnet kan variere fra en post til en anden.

   • Hver indgang siger, at println er en metode i klassen java. someStuff. someMoreStuff . Klassen kan variere fra en indgang til en anden.

     

     println-poster i API-dokumentationens indeks. ">
     Figur 3: Nogle println-poster i API-dokumentationens indeks.

   På dette tidspunkt betaler det sig at kaste sig rundt. Hvis du forsøger at udskrive noget som "Hej verden! ", Vil du have en af ​​println (String) poster. På den anden side vil du sandsynligvis vælge en println (dobbelt) post, hvis du forsøger at udskrive værdien af ​​lengthOfStraightLine.

   Antag nu, at du har besluttet dig for println (String). Du kan vælge mellem tre println (String) poster. Man siger, at det er en metode i klassen java. io. PrintStream, den næste er en metode i klassen java. io. PrintWriter, og den tredje er en metode i klassen java. sql. DriverManager. Hvilke af disse tre poster vælger du?

   Nå, hvad du virkelig forsøger at ringe er noget, der hedder System. ud. println. Hvis du går gennem hele lookup rigmarole med Systemout, finder du det System. out har typen PrintStream. (Se figur 4 nedenfor.) Så den println (String) post du vælger er

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

   

   out variabel har typen PrintStream. ">
   Figur 4: Ud-variablen har typen PrintStream.

5. Klik på linket for den indtastning, du har valgt.

   Når du klikker på linket println (String), fører browseren dig til en side, der forklarer en println-metode, som vist i Figur 5. Siden fortæller dig, hvad println gør ("Print a String and then …") og peger på andre nyttige sider, som siden med dokumentationen for String.

   

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

Brug af listen over klasser

Sådan finder du en post i API'en ved at starte i listen over klasser:

1. Besøg docs. Oracle. dk / javase / 8 / docs / api /.

2. Find den side, der dokumenterer System-klassen.

   Du leder efter dokumentation, der forklarer System. ud. println. Så du kigger op System, arbejde dig ud til, og derfra arbejde dig til println.

   For at finde et link til System, se i den nederste ramme på venstre side af siden. (Se figur 6.) For tips om at finde tekst på siden, se trin 3 i afsnittet "Brug af indekset".

   

   System klasse. ">
   Figur 6: Finde et link til systemklassen.

   Når du klikker på linket System, får din browser vist dokumentationssiden til systemklassen, som vist i figur 7.

   

   Dokumentarkitektens dokumentation. ”>
   figur 7: Systemklassens dokumentation.

3. Find ud af variablen på dokumentationssiden for systemklassen.

   Hvis du bruger din dialogboks Find Find, skal du klikke på knappen Find Next flere gange. (Navnet er så almindeligt, det vises flere gange i flere forskellige sammenhænge på siden Systemdokumentation.) Når du har fundet det, du leder efter, ser du et bord som det, der vises i figur 4 ovenfor.

4. Klik på linket PrintStream i tabelens rækkefølge.

   Ifølge dokumentationen henviser ud-variablen til et objekt af typen PrintStream.Det betyder, at println er en del af PrintStream-klassen. Derfor klikker du på PrintStream-linket.

5. Find println (String) på dokumentationssiden for PrintStream.

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

Du kan også gøre det

Når du har fulgt trinene i denne artikel, kan du blive fristet til at sige "Big deal! Jeg kan finde println i API docs, men jeg kan sikkert ikke finde noget andet. Og hvis folk opretter dokumentation for ting, som de selv programmerer, så vil deres dokumentation ikke ligne standard API-dokumentationen. Jeg kommer op i en bæk. "

Det rette svar på en sådan indsigelse er" Nonsens! Baloney! Vrøvl! Hestefjer! "Her er hvorfor:

• De fleste af de tricks du har brug for til at finde ting i standard Java-dokumentationen, er illustreret i denne artikels trinvise vejledning. Hvis du kan finde System. ud. println, kan du også finde javax. svinge. JButton eller et af de 4, 200 programmer i standard Java API.

  Og som du opdager mere om Java og forholdene mellem klasser, metoder og variabler, vil denne artikels trinvise instruktioner føle sig meget mere naturlig.

• For at læse andres dokumentation kan du ridse dette problem lige uden for din liste. Standard API-dokumenterne blev ikke skrevet manuelt. De blev genereret automatisk fra den aktuelle Java-programkode. For eksempel koden til PrintStream. java har et par linjer, der ser sådan ud:

  / ** * Udskriv en streng, og afslut derefter linjen. * Denne metode virker som om den påberåber *
  
  {@ link #print (String)}
  
  * og derefter
  
  {@ link #println ()}
  
  . * * @param x Den
  
  String
  
  , der skal udskrives. * /
  

  For at oprette API dokumentationen kørte kaptajnerne af Java et program kaldet javadoc . Javadoc-programmet tog linjer som disse lige ud af PrintStream. java-fil og brugte linjerne til at lave den dokumentation, du ser i din webbrowser.

  Andre Java-programmører gør det samme. Faktisk bruger alle, der skriver Java-kode, javadoc-programmet til at generere dokumentation. Så alles Java-dokumentation ligner alle andres Java-dokumentation. Når du ved, hvordan du læser standard API-dokumentationen, ved du, hvordan du læser nogens hjemmelavede Java-dokumenter.

  Og ja, du kan bruge javadoc-programmet til at oprette din egen dokumentation. Når du downloader JDK, får du javadoc-programmet som en del af aftalen.