streamalism.org

1. Áttekintés

A jó API dokumentáció a sok tényező egyike, amely hozzájárul egy szoftver projekt általános sikeréhez.

Szerencsére a JDK minden modern verziója biztosítja a Javadoc eszközt - az API dokumentáció előállításához a forráskódban található megjegyzésekből.

Előfeltételek:

1. JDK 1.4 (a Maven Javadoc plugin legújabb verziójához a JDK 7+ ajánlott)
2. A JDK /kuka mappa hozzáadva a PÁLYA környezeti változó
3. (Opcionális) egy IDE, amely beépített eszközökkel rendelkezik

2. Javadoc-megjegyzések

Kezdjük a megjegyzésekkel.

A Javadoc megjegyzések felépítése nagyon hasonlít egy szokásos többsoros megjegyzéshez, de a legfontosabb különbség az elején látható extra csillag:

// Ez egysoros megjegyzés / * * Ez egy szokásos többsoros megjegyzés * / / ** * Ez egy javadoc * /

A Javadoc stílusú megjegyzések tartalmazhatnak HTML címkéket is.

2.1. Javadoc formátum

A dzsádók megjegyzései minden olyan osztály, módszer vagy mező fölé helyezhetők, amelyet dokumentálni akarunk.

Ezeket a megjegyzéseket általában két szakasz alkotja:

1. A kommentálás leírása
2. Az önálló blokkcímkék („@”Szimbólum), amelyek specifikus metaadatokat írnak le

A példánkban néhány leggyakoribb blokkcímkét fogunk használni. A blokkcímkék teljes listáját a referencia útmutatóban találja.

2.2. Javadoc osztály szinten

Vessünk egy pillantást arra, hogy nézne ki egy osztály szintű Javadoc megjegyzés:

/ ** * A hős a fő entitás, amelyhez használni fogjuk. . . * * Az igaz személyazonosságot lásd a {@link com.baeldung.javadoc.Person} osztályban.

Rövid leírásunk van, és két különböző blokkcímke van: önálló és beépített:

• Önálló címkék jelennek meg a leírás után, a címke a sor első szavaként jelenik meg, pl @szerző címke
• A beillesztett címkék bárhol megjelenhetnek, és göndör zárójelek veszik körül őketpéldául a @link tag a leírásban

Példánkban kétféle blokkcímkét is láthatunk:

• {@link} tartalmaz egy belső linket a forráskód hivatkozott részéhez
• @szerző annak a szerzőnek a neve, aki hozzáadta a kommentelt osztályt, módszert vagy mezőt

2.3. Javadoc terepi szinten

Leírást is használhatunk anélkül, hogy ilyen blokkcímkék lennének Szuperhős osztály:

/ ** * A hős nyilvános neve, amely közismert * / private String heroName;

A privát mezőkhöz nem hoznak létre Javadoc-ot, hacsak kifejezetten nem adjuk át a -magán opciót a Javadoc parancsra.

2.4. Javadoc módszer szinten

A módszerek különféle Javadoc blokkcímkéket tartalmazhatnak.

Vessünk egy pillantást egy általunk használt módszerre:

/** * 
Ez a módszer egyszerű leírása. . . * Superman! * 
 * @param incomingKárosítsa a beérkező károk összegét * @visszaadja az egészségügyi hős támadás utáni mennyiségét. }

A sikeresen megtámadva A metódus leírást és számos önálló blokkcímkét is tartalmaz.

Sok blokkcímke segíti a megfelelő dokumentumok előállítását, és mindenféle, különféle információt tartalmazhatunk. Akár az alapvető HTML címkéket is felhasználhatjuk a megjegyzésekben.

Nézzük át a fenti példában szereplő címkéket:

• @param hasznos leírást ad a metódus paraméteréről vagy bemenetéről, amelyre számítania kell
• @Visszatérés leírást ad arról, hogy egy módszer mit hozhat vissza, vagy mit adhat vissza
• @lát hasonló linket generál {@link} tag, de inkább hivatkozás és nem inline összefüggésében
• @mivel meghatározza, hogy az osztály, mező vagy módszer melyik verzióval lett hozzáadva a projekthez
• @változat meghatározza a szoftver verzióját, amelyet általában% I% és% G% makrókkal használnak
• @ dob a továbbiakban magyarázza azokat az eseteket, amikor a szoftver kivételt várna
• @elavult magyarázatot ad arra, hogy miért volt elavult a kód, mikor lehet, hogy elavult, és mik az alternatívák

Bár technikailag mindkét szakasz opcionális, legalább egyre szükségünk lesz, hogy a Javadoc eszköz bármi értelmeset létrehozhasson.

3. Javadoc Generation

A Javadoc oldalak előállításához meg kell néznünk a JDK-val együtt szállított parancssori eszközt és a Maven plugint.

3.1. Javadoc parancssori eszköz

A Javadoc parancssori eszköz nagyon hatékony, de némi összetettséggel rendelkezik.

A parancs futtatása javadoc opciók és paraméterek nélkül hiba és kimeneti paraméterek várhatók.

Legalább meg kell határoznunk, hogy milyen csomaghoz vagy osztályhoz szeretnénk dokumentációt generálni.

Nyissunk meg egy parancssort, és keressük meg a projekt könyvtárat.

Feltéve, hogy az osztályok mind a src mappa a projekt könyvtárban:

[e-mail védett]: ~ $ javadoc -d doc src \ *

Ez dokumentációt generál az úgynevezett könyvtárban doc a -d zászló. Ha több csomag vagy fájl létezik, mindet meg kell adnunk.

Az IDE használata beépített funkcionalitással természetesen könnyebb és általában ajánlott.

3.2. Javadoc Maven pluginnal

Használhatjuk a Maven Javadoc plugint is:

   org.apache.maven.plugins maven-javadoc-plugin 3.0.0 1.8 1.8 ... 

A projekt alapkönyvtárában futtatjuk a parancsot, hogy létrehozzuk Javadocs-junkat a target \ site könyvtárba:

[e-mail védett]: ~ $ mvn javadoc: javadoc

A Maven plugin nagyon hatékony, és zökkenőmentesen elősegíti a komplex dokumentumgenerálást.

Most nézzük meg, hogyan néz ki egy létrehozott Javadoc oldal:

Láthatunk egy fa nézetet az osztályainkról Szuperhős osztály kiterjed. Láthatjuk leírásunkat, mezőket és módszerünket, és további információkért kattintson a linkekre.

A módszerünk részletes áttekintése így néz ki:

3.3. Egyéni Javadoc-címkék

Amellett, hogy előre definiált blokkcímkéket használ a dokumentációnk formázásához, létrehozhatunk egyedi blokkcímkéket is.

Ehhez csak be kell illesztenünk a -címke opciót a Javadoc parancssorunkhoz a ::.

Nevű egyéni címke létrehozása érdekében @elhelyezkedés bárhol megengedett, amely a létrehozott dokumentum „Figyelemre méltó helyek” fejlécében jelenik meg, futtatnunk kell:

[e-mail védett]: ~ $ javadoc -tag hely: a: "Figyelemre méltó helyek:" -d doc src \ *

A címke használatához hozzáadhatjuk a Javadoc megjegyzés blokk szakaszához:

/ ** * Ez egy példa ... * @helyszín New York * @returns blah blah * /

A Maven Javadoc plugin elég rugalmas ahhoz, hogy az egyéni címkéinket is meghatározhassa pom.xml.

Annak érdekében, hogy projektünkhöz a fenti címkét beállítsuk, a következőket adhatjuk hozzá a bővítményünk szakasza:

... egy figyelemre méltó helyek: ...

Ez lehetővé teszi számunkra, hogy egyszer megadjuk az egyéni címkét, ahelyett, hogy minden alkalommal megadnánk.

4. Következtetés

Ez a gyors bemutató bemutatta, hogyan kell írni az alapvető Javadocs-okat, és hogyan lehet őket létrehozni a Javadoc parancssor segítségével.

A dokumentáció előállításának egyszerűbb módja bármilyen beépített IDE opció használata, vagy a Maven plugin beépítése a mi oldalunkba pom.xml fájlt, és futtassa a megfelelő parancsokat.

A kódminták, mint mindig, a GitHubon találhatók.