Zmysluplnosť dokumentácie rozhrania Java API

Barry Burd

Kedysi ľudia posudzovali programovacie jazyky (vrátane Javy) iba podľa gramatických vlastností. Máakvyhlásenie urobte to, čo od neho očakávate? Používajú sa opakované vyhlásenia ľahko? Sú metódy implementované efektívne?



V dnešnej dobe je to trochu iné. Java má celú zbierku gramatických funkcií, ale Java je oveľa viac než len veľká sada gramatických pravidiel. Java má štandard Appl ication Programovacie rozhranie —Obrovská knižnica pozostávajúca z viac ako 4 000 tried, každá s vlastnou funkčnosťou, vlastnými obmedzeniami a vlastnými pravidlami efektívneho používania.



Hľadá sa výraz

Veci v dokumentácii API nájdete rôznymi spôsobmi. Každý spôsob je vhodný v tej či onej situácii. Napríklad Java má pomenovanú metóduSystem.out.println. Nasledujúci text popisuje dva spôsoby, ako vyhľadaťSystem.out.printlnmetóda.

Pomocou indexu

Tu je postup, ako nájsť niečo, ako naprSystem.out.printlnpomocou indexu:



  1. Navštívte docs.oracle.com/javase/8/docs/api/ .

  2. Kliknutím na odkaz INDEX v hornej časti stránky otvoríte index, ako je to znázornené na obrázku 1.

    Obrázok 1: Dokumentácia APIObrázok 1: Hlavná stránka dokumentácie API.

    Zoznam písmen sa nachádza v hornej časti indexu (pozri obrázok 2). Kliknutím na odkaz P prejdete do sekcie sprintlnv tom.



    Obrázok 2: Dokumentácia API/> Obrázok 2: Indexová stránka dokumentácie API.
  3. V časti P vyhľadajte výrazprintlnnájsťprintlnzáznamy.

    Väčšina webových prehľadávačov vám umožňuje vyhľadávať niečo podobnéprintlnv texte stránky. Tu je postup:

    1. Uistite sa, že prehľadávač vie, že chcete vyhľadávať vo veľkom rámci, ktorý zaberá väčšinu stránky (a nie v menších rámcoch na ľavej strane stránky). Ak to chcete urobiť, kliknite myšou do veľkého rámu. (Neklikajte na odkaz. Kliknite na neutrálnu bielu oblasť rámu.)

    2. V prehliadači otvorte dialógové okno Nájsť. Vo väčšine prehľadávačov systému Windows sa stlačením klávesovej skratky Ctrl + F skryje dialógové okno Hľadať. V systéme Mac klikanie na klávesy Command + F urobí trik.

    3. Keď sa zobrazí dialógové okno Nájsť, napíšteprintlndo textového poľa a kliknite na tlačidlo Nájsť alebo Nájsť ďalšie.

      tylenol na prázdny žalúdok
  4. Vyberte jednu z možnostíprintlnzáznamy.

    Úsek P má veľký náklad lodíprintlnpoložky, ako je znázornené na obrázku 3 nižšie. Položky sa navzájom líšia dvoma spôsobmi:

    • Každá položka hovoríprintln (int),println (reťazec)aleboprintln (someOtherTypeName). Názov typu sa môže líšiť od jednej položky k druhej.

    • Každá položka to hovoríprintlnje metóda v triedejava. someStuff.someMoreStuff . Trieda sa môže líšiť od jedného záznamu k druhému.

      položky println v indexe dokumentácie API ./> Obrázok 3: Niektoréprintlnpoložky v indexe dokumentácie API.

    V tomto okamihu sa oplatí makať. Ak sa pokúšate vytlačiť niečo akoAhoj svet!, chcete jednu zprintln (reťazec)záznamy. Na druhej strane, ak sa pokúšate vytlačiť hodnotuthengthOfStraightLine, pravdepodobne si vyberiete aprintln (double)vstup.

    Predpokladajme, že ste sa rozhodliprintln (reťazec). Môžete si vybrať z trochprintln (reťazec)záznamy. Jeden hovorí, že je to metóda v triedejava.io.PrintStream, ďalšia je metóda v triedejava.io.PrintWriter, a tretia je metóda v triedejava.sql.DriverManager. Ktorý z týchto troch záznamov si vyberiete?

    To, čo sa skutočne snažíte zavolať, je niečo pod menomSystem.out.println. Ak prejdete celým vyhľadávacím rigmarolom sSystemout, nájdete toSystem.outmá typPrintStream. (Pozri obrázok 4 nižšie.) Takžeprintln (reťazec)položka, ktorú sa rozhodnete zvoliť, je

    println (String) - Metóda v triede java.io.PrintStream.

    výstupná premenná má typPrintStream./> Obrázok 4:vonpremenná má typPrintStream.
  5. Kliknite na odkaz pri položke, ktorú ste vybrali.

    Keď kliknete na odkaz println (reťazec), prehliadač vás zavedie na stránku, ktorá vysvetľuje aprintlnmetóda, ako je to znázornené na obrázku 5. Stránka vám povie, čoprintln(Vytlačí reťazec a potom ...) a odkazuje na ďalšie užitočné stránky, napríklad na stránku s dokumentáciou preString.

    metóda println ./> Obrázok 5: Popis súboruprintlnmetóda.

Pomocou zoznamu tried

Tu je príklad, ako nájsť položku v API začatím v zozname tried:

  1. Navštívte docs.oracle.com/javase/8/docs/api/ .

  2. Nájdite stránku, ktorá dokumentujeSystémtrieda.

    Hľadáte dokumentáciu, ktorá vysvetľujeSystem.out.println. Takže vzhliadneteSystém, prepracujte savona odtiaľ sa prepracujteprintln.

    Nájsť odkaz naSystém, pozrite sa do spodného rámčeka na ľavej strane stránky. (Pozri obrázok 6.) Tipy na hľadanie textu na stránke nájdete v kroku 3 v časti Používanie indexu.

    Trieda systému ./> Obrázok 6: Vyhľadanie odkazu naSystémtrieda.

    Kliknutím na prepojenie Systém váš prehliadač zobrazí stránku s dokumentáciou preSystémtriedy, ako je znázornené na obrázku 7.

    Dokumentácia triedy systému ./> Obrázok 7:Systémdokumentácia triedy.
  3. Na stránke dokumentácie kSystémtriedy, nájdivonpremenná.

    Ak používate dialógové okno Nájsť vo svojom webovom prehliadači, musíte niekoľkokrát kliknúť na tlačidlo Nájsť ďalej. (Názovvonje také bežné, objavuje sa niekoľkokrát v niekoľkých rôznych kontextoch na interneteSystémstránka s dokumentáciou.) Keď nájdete to, čo hľadáte, zobrazí sa tabuľka, ako je tabuľka uvedená na obrázku 4 vyššie.

  4. V tabuľkevonriadku kliknite na odkaz PrintStream.

    Podľa dokumentácievonpremenná odkazuje na objekt typuPrintStream. To znamená, žeprintlnje súčasťouPrintStreamtrieda. Preto klikáte na ikonuPrintStreamodkaz.

  5. Na stránke dokumentácie prePrintStream, Nájsťprintln (reťazec).

    Vysvetlenie sa zobrazuje podobne ako na obrázku 5 vyššie.

Dokážeš to tiež

Po vykonaní krokov v tomto článku vás môže lákať povedať: Veľký problém! Môžem nájsťprintlnv dokumentoch API, ale asi nenájdem nič iné. A ak ľudia vytvoria dokumentáciu pre veci, ktoré programujú sami, nebude ich dokumentácia vyzerať ako štandardná dokumentácia API. Budem hore potokom.

Vhodnou reakciou na takúto námietku je nezmysel! Baloney! Balderdash! Konské perie! Tu je dôvod, prečo:

  • Väčšina trikov, ktoré potrebujete pri hľadaní vecí v štandardnej dokumentácii Java, je ilustrovaná v podrobných pokynoch tohto článku. Ak nájdeteSystem.out.println, môžete tiež nájsťjavax.swing.JButtonalebo ktorýkoľvek z 4 200 programov v štandardnom Java API.

    A keď sa dozviete viac o prostredí Java a vzťahoch medzi triedami, metódami a premennými, podrobné pokyny tohto článku budú pôsobiť oveľa prirodzenejšie.

  • Pokiaľ ide o čítanie dokumentácie iných ľudí, môžete tento problém poškriabať priamo zo zoznamu. Štandardné dokumenty API neboli písané ručne. Boli generované automaticky zo skutočného programového kódu Java. Napríklad kód prePrintStream.javamá niekoľko riadkov, ktoré vyzerajú asi takto:

    {@link #print(String)}

    Na vytvorenie dokumentácie API spustili kapitáni Javy program s názvom javadoc . Program javadoc vzal takéto riadky priamo zPrintStream.javasúbor a pomocou riadkov vytvorili dokumentáciu, ktorú vidíte vo svojom webovom prehliadači.

    To isté robia aj ostatní programátori Java. V skutočnosti každý, kto píše kód Java, používa program javadoc na generovanie dokumentácie. Takže dokumentácia Java všetkých vyzerá ako dokumentácia Java všetkých ostatných. Keď viete, ako čítať štandardnú dokumentáciu API, viete čítať hocijaké domáce dokumenty Java.

    A áno, na vytvorenie vlastnej dokumentácie môžete použiť program javadoc. Keď si stiahnete JDK, dostanete program Javadoc ako súčasť dohody.