Sense of Java's API-documentatie maken - dummies

Mensen beoordeelden programmeertalen (inclusief Java) uitsluitend op basis van hun grammaticale functies. Doet een if-statement wat u ervan verwacht? Zijn lusinstructies eenvoudig te gebruiken? Worden methoden efficiënt geïmplementeerd?

Tegenwoordig zijn de zaken een beetje anders. Java heeft een hele verzameling grammaticale functies, maar Java is veel meer dan alleen een grote verzameling grammaticaregels. Java heeft een standaard Appl ication Programming Interface - een enorme bibliotheek die bestaat uit meer dan 4.000 klassen, elk met zijn eigen functionaliteit, eigen beperkingen en eigen regels voor effectief gebruik.

Zoeken naar een term

U kunt dingen in de API-documentatie op verschillende manieren vinden. Elke manier is handig in de ene of andere situatie. Java heeft bijvoorbeeld een methode met de naam Systeem. uit. println. Hieronder worden twee manieren beschreven om het systeem op te zoeken. uit. println-methode.

De index gebruiken

Hier leest u hoe u iets kunt vinden, zoals Systeem. uit. println, door de index te gebruiken:

1. Documenten bekijken. orakel. com / JavaSE / 8 / docs / api /.

2. Klik op de INDEX-koppeling bovenaan de pagina om de index te openen, zoals weergegeven in afbeelding 1.

   

   Afbeelding 1: de hoofdpagina van de API-documentatie.

   Een lijst met letters staat bovenaan de index (zie afbeelding 2). Klik op de P-koppeling om naar het gedeelte met println te gaan.

   

   “>
   figuur 2: de indexpagina van de API-documentatie.

3. Zoek in het gedeelte P naar println om de afdrukken te vinden.

   In de meeste webbrowsers kunt u naar iets als println zoeken in de tekst van een pagina. Ga als volgt te werk:

   1. zorg ervoor dat de browser weet dat u wilt zoeken in het grote frame dat het grootste deel van de pagina beslaat (en niet in de kleinere frames aan de linkerkant van de pagina). Om dit te doen, klik je met je muis in het grote frame. (Klik niet op een koppeling. Klik op een neutraal wit gedeelte van het kader.)

   2. Open het dialoogvenster Zoeken van de browser. In de meeste Windows-browsers leidt het drukken op Ctrl + F ertoe dat het dialoogvenster Zoeken niet meer verborgen blijft. Op een Mac, klikt u op Command + F.

   3. Wanneer u het dialoogvenster Zoeken ziet, typt u println in het tekstvak en klikt u op de knop Zoeken of Zoeken op de doos.

4. Kies een van de println-vermeldingen.

   De P-sectie heeft een grote lading println-vermeldingen, zoals weergegeven in Afbeelding 3 hieronder. De items verschillen op twee manieren van elkaar:

   • Elk item zegt println (int), println (String) of println (someOtherTypeName). De typenaam kan van item tot item verschillen.

   • Elke invoer zegt dat println een methode is in de klasse java. someStuff. someMoreStuff . De klasse kan van item tot item verschillen.

     

     println-vermeldingen in de index van de API-documentatie. ">
     Afbeelding 3: enkele println-vermeldingen in de index van de API-documentatie.

   Op dit moment loont het om rond te snuffelen. Als je iets als "Hallo wereld! ", Wilt u een van de println (String) -items. Als u daarentegen de waarde van lengthOfStraightLine probeert af te drukken, kiest u waarschijnlijk een println (dubbel) -item.

   Stel nu dat u hebt beslist over println (String). U kunt uit drie println (String) -items kiezen. Men zegt dat het een methode is in de klasse java. io. PrintStream, de volgende is een methode in de klasse java. io. PrintWriter, en de derde is een methode in de klasse java. sql. DriverManager. Welke van deze drie items kiest u?

   Wel, wat u echt probeert te noemen, is iets genaamd System. uit. println. Als je de hele lookup-rigmarole doorloopt met Systemout, zul je dat systeem vinden. uit heeft type PrintStream. (Zie Figuur 4 hieronder.) Dus de println (String) -vermelding die u wilt kiezen, is

   println (String) - Methode in java van klasse. io. PrintStream.

   

   uit variabele heeft het type PrintStream. ">
   Afbeelding 4: De variabele out heeft het type PrintStream.

5. Klik op de koppeling voor het item dat u heeft gekozen.

   Wanneer u op de koppeling println (String) klikt, gaat de browser naar een pagina met een methode println, zoals weergegeven in afbeelding 5. Op de pagina ziet u wat println doet ("Print a String and then …") en verwijst naar andere nuttige pagina's, zoals de pagina met de documentatie voor String.

   

   println-methode. ">
   Afbeelding 5: een beschrijving van de println-methode.

De lijst met klassen gebruiken

U kunt als volgt een item in de API zoeken door in de lijst met klassen te starten:

1. Documenten bekijken. orakel. com / JavaSE / 8 / docs / api /.

2. Zoek de pagina met de systeemklasse.

   U zoekt documentatie die systeem uitlegt. uit. println. Dus je zoekt Systeem op, werkt je weg naar buiten en werkt vanaf daar naar println.

   Als u een link naar het systeem wilt zoeken, kijkt u in het onderste frame aan de linkerkant van de pagina. (Zie afbeelding 6.) Zie stap 3 in het gedeelte "De index gebruiken" voor hints voor het vinden van tekst op de pagina.

   

   Systeemklasse. ">
   Figuur 6: Een koppeling zoeken naar de klasse System.

   Als u op de koppeling System klikt, wordt in uw browser de documentatiepagina voor de klasse System weergegeven, zoals weergegeven in afbeelding 7.

   

   Documentatie over de systeemklasse. “>
   figuur 7: de documentatie van de systeemklasse.

3. Zoek op de documentatiepagina voor de klasse System de variabele out.

   Als u het dialoogvenster Zoeken van uw webbrowser gebruikt, moet u meerdere keren op de knop Volgende zoeken klikken. (De naam is zo gewoon, deze verschijnt meerdere keren in verschillende contexten op de systeemdocumentatiepagina.) Als je hebt gevonden waarnaar je op zoek bent, zie je een tabel zoals die in figuur 4 hierboven.

4. Klik in de rij van de tabel op de koppeling PrintStream.

   Volgens de documentatie verwijst de out-variabele naar een object van het type PrintStream.Dit betekent dat println deel uitmaakt van de PrintStream-klasse. Daarom klik je op de PrintStream-link.

5. Zoek op de documentatiepagina voor PrintStream naar println (tekenreeks).

   Je ziet een verklaring zoals die in figuur 5 hierboven.

U kunt het ook doen

Nadat u de stappen in dit artikel hebt gevolgd, komt u misschien in de verleiding om te zeggen: "Big deal! Ik kan println vinden in de API-documenten, maar ik kan waarschijnlijk niets anders vinden. En als mensen documentatie maken voor dingen die ze zelf programmeren, dan zal hun documentatie er niet uitzien als de standaard API-documentatie. Ik kom in een kreek. "

Het juiste antwoord op een dergelijk bezwaar is" Onzin! Onzin! Onzin! Paardenveren! "Dit is waarom:

• De meeste trucs die je nodig hebt om dingen te vinden in de standaard Java-documentatie, worden geïllustreerd in de stapsgewijze instructies van dit artikel. Als je systeem kunt vinden. uit. println, je kunt ook javax vinden. schommel. JButton of een van de 4, 200 programma's in de standaard Java API.

  En als u meer ontdekt over Java en de relaties tussen klassen, methoden en variabelen, zullen de stapsgewijze instructies van dit artikel veel natuurlijker aanvoelen.

• Zoals voor het lezen van de documentatie van andere mensen, kunt u dat probleem meteen uit uw lijst schrappen. De standaard API-documenten zijn niet met de hand getypt. Ze werden automatisch gegenereerd op basis van de eigenlijke Java-programmacode. Bijvoorbeeld de code voor PrintStream. java heeft een paar regels die er ongeveer zo uitzien:

  / ** * Druk een tekenreeks af en beëindig de regel. * Deze methode gedraagt ​​zich alsof deze *
  
  {@ link #print (String)}
  
  * en vervolgens
  
  {@ link #println ()}
  
  aanroept. * * @param x De
  
  String
  
  die moet worden afgedrukt. * /
  

  Om de API-documentatie te maken, hebben de hoofdmanagers van Java een programma uitgevoerd met de naam javadoc . Het javadoc-programma nam dergelijke lijnen rechtstreeks uit de PrintStream. java-bestand en gebruikte de regels om de documentatie te maken die u in uw webbrowser ziet.

  Andere Java-programmeurs doen hetzelfde. In feite gebruikt iedereen die Java-code schrijft het javadoc-programma om documentatie te genereren. Dus de Java-documentatie van iedereen ziet eruit als de Java-documentatie van iedereen. Wanneer u weet hoe de standaard API-documentatie wordt gelezen, weet u hoe u iemands homegrown Java-documenten moet lezen.

  En ja, u kunt het javadoc-programma gebruiken om uw eigen documentatie te maken. Wanneer u de JDK downloadt, krijgt u het javadoc-programma als onderdeel van de deal.