Deltagare av Java: s API-dokumentation - dummies

Därefter bedömde människor programmeringsspråk (inklusive Java) enbart genom sina grammatiska egenskaper. Gör ett if-uttalande vad du förväntar dig att göra? Är looping statements lätt att använda? Är metoderna genomförda effektivt?

Idag är sakerna lite annorlunda. Java har en hel samling grammatiska funktioner, men Java är mycket mer än bara en stor uppsättning grammatikregler. Java har en standard Appl ication Programmeringsgränssnitt - ett stort bibliotek som består av över 4 000 klasser, alla med egen funktionalitet, egna begränsningar och egna regler för effektiv användning.

Söka efter en term

Du kan hitta saker i API-dokumentationen på ett antal olika sätt. Varje väg är bekväm i en situation eller en annan. Till exempel har Java en metod som heter System. ut. println. Det följande beskriver två sätt att leta upp systemet. ut. println metod.

Använda indexet

Här hittar du något, till exempel System. ut. println, genom att använda indexet:

1. Besök docs. orakel. com / JavaSE / 8 / docs / api /.

2. Klicka på INDEX-länken längst upp på sidan för att öppna indexet, som visas i Figur 1.

   

   Figur 1: API-dokumentationens huvudsida.

   En lista med bokstäver ligger nära toppen av indexet (se figur 2). Klicka på P-länken för att gå till sektionen med println i den.

   

   ”>
   figur 2: API-dokumentationens indexsida.

3. I sektionen P gör du en sökning efter println för att hitta println-posterna.

   Med de flesta webbläsare kan du söka efter något som println i texten på en sida. Så här:

   1. Se till att webbläsaren vet att du vill söka i den stora ramen som tar upp det mesta av sidan (och inte i de mindre ramarna till vänster på sidan). För att göra detta, klicka på musen inuti den stora ramen. (Klicka inte på en länk. Klicka på något neutralt vitt område i ramen.)

   2. Öppna webbläsarens Sök dialogruta. På de flesta Windows-webbläsare samlar du Ctrl + F i dialogrutan Sök bort från att gömma sig. På en Mac klickar Kommando + F på tricket.

   3. När du ser dialogrutan Sök, skriv skriv ut i textrutan och klicka på rutan Sök eller Sök nästa.

4. Välj en av println-posterna.

   P-sektionen har en stor båtlängd av println-poster, som visas i Figur 3 nedan. Uppgifterna skiljer sig från varandra på två sätt:

   • Varje post anger println (int), println (String) eller println (someOtherTypeName). Typnamnet kan skilja sig från en post till en annan.

   • Varje post säger att println är en metod i klass java. someStuff. someMoreStuff . Klassen kan skilja sig från en post till en annan.

     

     println-poster i API-dokumentationens index. ">
     Figur 3: Vissa println-poster i API-dokumentationens index.

   Vid den här tiden löser det sig att koka runt. Om du försöker skriva ut något som "Hej värld! ", Du vill ha en av println (String) poster. Å andra sidan, om du försöker skriva ut värdet av lengthOfStraightLine, väljer du förmodligen en dubbel (dubbel) post.

   Anta att du har bestämt dig för println (String). Du kan välja mellan tre println (String) poster. En säger att det är en metod i klass java. io. PrintStream, nästa är en metod i klass java. io. PrintWriter, och den tredje är en metod i klass java. SQL. Driver. Vilken av dessa tre poster väljer du?

   Tja, vad du verkligen försöker ringa är något som heter System. ut. println. Om du går igenom hela lookup-rigmarolen med Systemout hittar du det Systemet. ut har typ PrintStream. (Se figur 4 nedan.) Så den println (String) post du väljer att välja är

   println (String) - Metod i klass java. io. Print.

   

   ut variabeln har typ PrintStream. ">
   Figur 4: Ut-variabeln har typ PrintStream.

5. Klicka på länken för den post som du har valt.

   När du klickar på länken println (String) tar du webbläsaren till en sida som förklarar en println-metod, som visas i Figur 5. Sidan berättar vilken println som görs ("Skriv ut en sträng och sedan …") och pekar på andra användbara sidor, som sidan med dokumentationen för String.

   

   println-metod. ">
   Figur 5: En beskrivning av println-metoden.

Använd lista över klasser

Så här hittar du en post i API: n genom att börja i listan med klasser:

1. Besök docs. orakel. com / JavaSE / 8 / docs / api /.

2. Hitta den sida som dokumenterar System-klassen.

   Du letar efter dokumentation som förklarar System. ut. println. Så du tittar upp System, jobba dig ut och därifrån jobbar du till println.

   För att hitta en länk till System, kolla in den nedre ramen till vänster på sidan. (Se Figur 6.) För tips om att hitta text på sidan, se Steg 3 i avsnittet "Använda index".

   

   Systemklass. ">
   Figur 6: Hitta en länk till systemklassen.

   Klicka på länken System gör att webbläsaren visar dokumentationssidan för systemklassen, som visas i Figur 7.

   

   Systemklassens dokumentation. ”>
   figur 7: Systemklassens dokumentation.

3. På sidan för dokumentation för systemklassen, hitta ut variabeln.

   Om du använder din webbläsares Sök-dialogruta måste du klicka på knappen Sök efter flera gånger. (Namnet är så vanligt, det visas flera gånger i flera olika sammanhang på sidan Systemdokumentation.) När du har hittat det du letar efter ser du ett bord som det som visas i Figur 4 ovan.

4. Klicka på länken PrintStream i tabellens rad.

   Enligt dokumentationen avser ut-variabeln ett objekt av typen PrintStream.Det betyder att println är en del av PrintStream-klassen. Därför klickar du på länken PrintStream.

5. På dokumentationssidan för PrintStream, hitta println (String).

   Du ser en förklaring som den som visas i Figur 5 ovan.

Du kan också göra det

När du har följt stegen i den här artikeln kan du bli frestad att säga "Big deal! Jag kan hitta println i API docs, men jag kan nog inte hitta något annat. Och om folk skapar dokumentation för saker som de själva programmerar, så kommer deras dokumentation inte att se ut som standard API-dokumentation. Jag kommer upp en bäck. "

Det lämpliga svaret på en sådan invändning är" Nonsens! Struntprat! Gallimatias! Hästfjädrar! "Det här är varför:

• De flesta av de knep du behöver för att hitta saker i standard Java-dokumentationen illustreras i den här artikeln, stegvisa instruktioner. Om du hittar System. ut. println, du kan också hitta javax. svänga. JButton eller något av de 4, 200-programmen i standard Java API.

  Och när du upptäcker mer om Java och relationerna mellan klasser, metoder och variabler, kommer den här artikeln steg för steg att känna sig mycket mer naturlig.

• När du läser andras dokumentation kan du reporera det problemet direkt från din lista. Standard API-dokumenten skrivs inte för hand. De genererades automatiskt från den aktuella Java-programkoden. Till exempel koden för PrintStream. java har några rader som ser något ut så här:

  / ** * Skriv ut en sträng och avsluta sedan raden. * Denna metod beter sig som om den påstår *
  
  {@ link #print (String)}
  
  * och sedan
  
  {@ link #println ()}
  
  . * * @param x Den
  
  Sträng
  
  som ska skrivas ut. * /
  

  För att skapa API-dokumentationen körde cheferna på Java ett program som heter javadoc . Javadoc-programmet tog linjer som dessa direkt ut ur PrintStream. java-filen och använde linjerna för att göra dokumentationen som du ser i din webbläsare.

  Andra Java-programmerare gör samma sak. Faktum är att alla som skriver Java-kod använder javadoc-programmet för att generera dokumentation. Så allas Java-dokumentation ser ut som alla andra Java-dokumentation. När du vet hur du läser standard API-dokumentation vet du hur man läser någons hemgrannade Java-dokument.

  Och ja, du kan använda javadoc-programmet för att skapa din egen dokumentation. När du laddar ner JDK får du javadoc-programmet som en del av affären.