streamalism.org

1. Prehľad

Dobrá dokumentácia API je jedným z mnohých faktorov prispievajúcich k celkovému úspechu softvérového projektu.

Našťastie všetky moderné verzie JDK poskytujú nástroj Javadoc - na generovanie dokumentácie API z komentárov prítomných v zdrojovom kóde.

Predpoklady:

1. JDK 1.4 (pre najnovšiu verziu pluginu Maven Javadoc sa odporúča JDK 7+)
2. The JDK / bin priečinok pridaný do priečinka CESTA premenná prostredia
3. (Voliteľné) IDE so zabudovanými nástrojmi

2. Javadoc komentáre

Začnime komentármi.

Štruktúra komentárov Javadoc vyzerá veľmi podobne ako bežný viacriadkový komentár, ale kľúčovým rozdielom je extra hviezdička na začiatku:

// Toto je jednoriadkový komentár / * * Toto je bežný viacriadkový komentár * / / ** * Toto je Javadoc * /

Komentáre v štýle Javadoc môžu obsahovať tiež značky HTML.

2.1. Formát Javadoc

Komentáre Javadoc je možné umiestniť nad akúkoľvek triedu, metódu alebo pole, ktoré chceme zdokumentovať.

Tieto komentáre sa zvyčajne skladajú z dvoch častí:

1. Opis toho, čo komentujeme
2. Samostatné blokové značky (označené značkou „@“), Ktoré popisujú konkrétne metaúdaje

V našom príklade použijeme niektoré z bežných blokových značiek. Úplný zoznam blokových značiek nájdete v referenčnej príručke.

2.2. Javadoc na úrovni triedy

Pozrime sa, ako by vyzeral komentár Javadocu na úrovni triedy:

/ ** * Hero je hlavná entita, na ktorú budeme zvyknutí. . . * * Skutočnú identitu nájdete v triede {@link com.baeldung.javadoc.Person} * @author Captain America * * / verejná trieda SuperHero rozširuje Person {// polia a metódy}

Máme krátky popis a dve rôzne blokové značky - samostatné a vložené:

• Samostatné značky sa objavia po opise so značkou ako prvé slovo v riadku, napr @autor značka
• Vložené riadky sa môžu objaviť kdekoľvek a sú obklopené zloženými zátvorkami, napr @ odkaz tag v popise

V našom príklade môžeme tiež vidieť dva druhy použitých blokových značiek:

• {@link} poskytuje priamy odkaz na odkazovanú časť nášho zdrojového kódu
• @autor meno autora, ktorý pridal komentovanú triedu, metódu alebo pole

2.3. Javadoc na úrovni poľa

Môžeme tiež použiť popis bez akýchkoľvek blokových značiek, ako je tento, v našom SuperHero trieda:

/ ** * Verejné meno hrdinu, ktoré je všeobecne známe * / private String heroName;

Súkromné ​​polia nebudú mať pre nich vygenerovaný Javadoc, pokiaľ výslovne nepostúpime -súkromné možnosť príkazu Javadoc.

2.4. Javadoc na úrovni metódy

Metódy môžu obsahovať rôzne značky blokov Javadoc.

Pozrime sa na metódu, ktorú používame:

/** * 
Toto je jednoduchý opis metódy. . . * Superman! * 
 * @param incomingZničte množstvo prichádzajúcich škôd * @ návratnosť množstva zdravotných hrdinov po útoku * @viz HERO-402 * @od 1.0 * / public int úspešneAttacked (int incomingDamage) {// vrátia veci 0; }

The úspešneAttacked metóda obsahuje popis aj množstvo samostatných blokových značiek.

Existuje veľa blokových značiek, ktoré nám pomáhajú generovať správnu dokumentáciu, a môžeme do nej zahrnúť najrôznejšie informácie. V komentároch môžeme dokonca použiť základné značky HTML.

Prejdime si značky, s ktorými sa stretávame v príklade vyššie:

• @param poskytuje akýkoľvek užitočný popis parametra alebo vstupu metódy, ktorý by mal očakávať
• @ návrat poskytuje popis toho, čo metóda bude alebo môže vrátiť
• @ pozri vygeneruje odkaz podobný {@link} značka, ale viac v kontexte referencie a nie vložené
• @since určuje, ktorá verzia, trieda, pole alebo metóda boli do projektu pridané
• @verzia určuje verziu softvéru, ktorá sa bežne používa v makrách% I% a% G%
• @ hody sa používa na ďalšie vysvetlenie prípadov, v ktorých by softvér očakával výnimku
• @ zastaraný poskytuje vysvetlenie, prečo bol kód zastaraný, kedy mohol byť zastaraný a aké sú alternatívy

Aj keď sú obe sekcie technicky voliteľné, na vygenerovanie čohokoľvek zmysluplného budeme potrebovať aspoň jednu, aby nástroj Javadoc.

3. Generácia Javadoc

Aby sme mohli vygenerovať naše stránky Javadoc, budeme sa chcieť pozrieť na nástroj príkazového riadku dodávaný s JDK a doplnok Maven.

3.1. Nástroj príkazového riadku Javadoc

Nástroj príkazového riadku Javadoc je veľmi výkonný, ale je s ním spojená nejaká zložitosť.

Spustenie príkazu javadoc bez akýchkoľvek volieb alebo parametrov bude mať za následok chybu a očakávané výstupné parametre.

Budeme musieť aspoň určiť, pre aký balík alebo triedu chceme dokumentáciu vygenerovať.

Poďme otvoriť príkazový riadok a prejsť do adresára projektu.

Za predpokladu, že sú všetky triedy v src priečinok v adresári projektu:

[chránené e-mailom]: ~ $ javadoc -d doc src \ *

Týmto sa vygeneruje dokumentácia v adresári s názvom doc ako je uvedené v -d vlajka. Ak existuje viac balíkov alebo súborov, budeme musieť poskytnúť všetky.

Využitie IDE so zabudovanou funkčnosťou je samozrejme jednoduchšie a všeobecne sa odporúča.

3.2. Javadoc s doplnkom Maven

Môžeme tiež využiť doplnok Maven Javadoc:

   org.apache.maven.plugins maven-javadoc-plugin 3.0.0 1,8 1,8 ... 

V základnom adresári projektu spustíme príkaz na vygenerovanie našich Javadocs do adresára v target \ site:

[chránené e-mailom]: ~ $ mvn javadoc: javadoc

Plugin Maven je veľmi výkonný a bezproblémovo uľahčuje generovanie zložitých dokumentov.

Pozrime sa teraz, ako vyzerá vygenerovaná stránka Javadoc:

Môžeme vidieť stromový pohľad na naše triedy SuperHero trieda predlžuje. Vidíme náš popis, polia a metódu a kliknutím na odkazy zobrazíme ďalšie informácie.

Podrobný pohľad na našu metódu vyzerá takto:

3.3. Vlastné značky Javadoc

Okrem použitia preddefinovaných blokových značiek na formátovanie našej dokumentácie, môžeme tiež vytvoriť vlastné blokové značky.

Aby sme tak mohli urobiť, stačí zahrnúť a -štítok možnosť do nášho príkazového riadku Javadoc vo formáte ::.

S cieľom vytvoriť vlastnú značku s názvom @ umiestnenie povolené kdekoľvek, ktoré sa zobrazuje v hlavičke „Notable Locations“ v našom generovanom dokumente, musíme spustiť:

[chránené e-mailom]: ~ $ javadoc -tag location: a: "Významné miesta:" -d doc src \ *

Aby sme mohli túto značku použiť, môžeme ju pridať do blokovej časti komentára Javadoc:

/ ** * Toto je príklad ... * @location New York * @returns bla bla * *

Doplnok Maven Javadoc je dostatočne flexibilný, aby umožnil aj definície našich vlastných značiek v našom pom.xml.

Za účelom nastavenia rovnakej značky vyššie pre náš projekt, môžeme pridať nasledujúce do časť nášho pluginu:

... umiestnenie významných miest: ...

Týmto spôsobom nám umožňuje určiť vlastnú značku raz, namiesto toho, aby sme ju zadávali zakaždým.

4. Záver

Tento rýchly úvodný úvod sa venoval spôsobu písania základných Javadocs a ich generovania pomocou príkazového riadku Javadoc.

Jednoduchší spôsob generovania dokumentácie by bolo použitie akýchkoľvek zabudovaných možností IDE alebo zahrnutie doplnku Maven do nášho pom.xml súbor a spustite príslušné príkazy.

Ukážky kódu, ako vždy, nájdete na GitHub.