Automatiškai dokumentuokite savo „Java“ kodą naudodami „Javadoc“.

Jei atliekate bet kokį programavimą, puikiai žinosite, kad viena iš varginančių užduočių yra kodo dokumentavimas. Nesvarbu, ar tai šiek tiek erzina, ar įsipareigojimas, su kuriuo susiduriate su visiška baime, kodo dokumentacija yra būtina. Kiti turi suprasti, kaip veikia jūsų kodas, ir jūs netgi galite būti vienas iš jų, jei jį skaitysite vėliau!

Java patogiai pateikia integruotą problemos sprendimą: Javadoc.

„Javadoc“ gali padėti automatiškai užregistruoti kodą

Tikimės, kad jau sekate gera kodavimo praktika ir į savo kodą įtraukite aiškinamuosius komentarus. Nors tokio tipo komentavimas kode yra tikrai naudingas, jis tikrai nepateikia nieko panašaus į vadovą.

Žinoma, kitas programuotojas gali peržiūrėti jūsų kodą ir perskaityti apie konkrečias klases, metodus ir funkcijas, kurios yra prieš jį. Tačiau labai sunku gauti gerą viso kodo apžvalgą arba rasti funkcijų, kurios galėtų būti naudingos, kai nežinote, kad jos egzistuoja. „Javadoc“ siekia išspręsti šią problemą.

„Javadoc“ automatiškai sugeneruos išsamų ir patogią skaityti HTML vadovą visam jūsų kodui. Geriausia, kad tai daroma naudojant kodo komentarus, kuriuos tikriausiai jau rašote.

Kas tiksliai yra „Javadoc“ ir kaip jis veikia?

„Javadoc“ yra atskira programa, kuri pateikiama kartu su „Oracle“ Java kūrimo rinkinio (JDK) leidimais. Tiesą sakant, jūs negalite jo atsisiųsti atskirai. Kai atsisiunčiate ir įdiekite vieną iš „Oracle“ JDK versijų, jis taip pat įdiegs „Javadoc“.

Kai paleidžiate, „Javadoc“ sukuria HTML dokumentaciją iš specialiai suformatuotų komentarų jūsų „Java“ šaltinio kode. Šis procesas sukuria naudingesnius, skaitomesnius dokumentus, taip pat skatina geriausią praktiką.

Trumpai tariant, „Javadoc“ suteikia galimybę vienu metu parašyti kodą ir jo dokumentus. Tai supaprastina darbo eigą ir leidžia efektyviau išnaudoti savo laiką.

„Javadoc“ veikia analizuodama specialiai suformatuotus komentarus jūsų kode ir konvertuodama juos į HTML išvestį. Vienintelis pakeitimas, kurį tikrai reikia padaryti, yra įtraukti tam tikras eilutes į savo komentarus. Tai leidžia „Javadoc“ žinoti, ką norite įtraukti į galutinę dokumentaciją.

Javadoc komentarai turėtų būti iš karto prieš klasės, lauko, konstruktoriaus ar metodo deklaraciją. Pats komentaras turėtų:

• Pradėkite nuo trijų simbolių /**.
• Kiekvienos naujos eilutės pradžioje įtraukite žvaigždutę.
• Uždarykite su dviem simboliais */.

Komentaruose galite įtraukti HTML į galutinę išvestį ir įtraukti žymas, kurios sukurs nuorodas į atitinkamas jūsų kodų bazės dalis. Norėdami įtraukti vaizdus į galutinę dokumentaciją, netgi galite naudoti tokius dalykus kaip HTML vaizdo žymos. Kai pripranti prie formato ir turimų žymų, tokius komentarus rašyti lengva.

Štai pavyzdys, iliustruojantis paprastus Javadoc komentarus, apibūdinančius funkciją, kuri gauna vaizdą iš URL ir išspausdina jį ekrane. Komentaras yra iš karto prieš funkciją ir aprašo, ką ji atlieka. Šiame komentarų bloke taip pat naudojamos trys konkrečios skilties žymos: @param, @grįžti, ir @pamatyti.

/**
* Grąžina vaizdo objektą, kurį vėliau galima nupiešti ekrane.
* URL argumentas turi nurodyti absoliutų skaičių {@link URL}. Pavadinimas
* argumentas yra specifikacija, susijusi su url argumentu.
* 

* Šis metodas visada grįžta iš karto, nesvarbu, ar jis
* Vaizdas yra. Kada tai programėlė bando nupiešti vaizdą
* ekrane, duomenys bus įkelti. Grafikos primityvai
* piešiantys vaizdą palaipsniui taps ekrane.
*
* @param url yra absoliutus URL, nurodantis pagrindinę vaizdo vietą
* @param pavadinkite vaizdo vietą, palyginti su url argumentu
* @grįžti paveikslėlį nurodytu URL adresu
* @pamatyti Vaizdas
*/
viešas Vaizdas gautiImage(URL URL, eilutės pavadinimas){
bandyti {
grąžinti gautiImage (naujas URL(url, vardas));
 } sugauti (Klaidingai suformuota URL išimtis e) {
grąžintinulinis;
 }
}

Kai „Javadoc“ apdoroja aukščiau pateiktą kodą, jis sukuria tinklalapį, panašų į šį:

Naršyklė pateikia „Javadoc“ išvestį beveik taip pat, kaip rodo bet kurį HTML dokumentą. Javadoc nepaiso papildomų tarpų ir eilučių pertraukų, nebent naudojate HTML žymas, kad sukurtumėte tą tarpą.

@žymės, naudojamos komentaro pabaigoje, sukuria Parametrai, Grąžina, ir Taip pat žr skiltys, kurias matote.

Turėtumėte vadovautis @param žyma su parametro pavadinimu, tarpu ir jo aprašymu. Pirmiau nurodytu atveju yra du parametrai: url ir vardas. Atkreipkite dėmesį, kad dokumentacijos išvestyje abu rodomi ta pačia antrašte Parameters. Galite nurodyti tiek parametrų, kiek reikia aprašomai funkcijai ar metodui.

The @grįžti žyma dokumentuoja reikšmę, kurią funkcija grąžina, jei tokia yra. Tai gali būti paprastas vieno žodžio aprašymas arba daug sakinių, priklausomai nuo aplinkybių.

The @pamatyti žyma leidžia pažymėti kitas susijusias ar svarbias funkcijas. Šiuo atveju @see žyma nurodo kitą funkciją, vadinamą tiesiog vaizdu. Atminkite, kad su šia žyma padarytos nuorodos yra nuorodos, kurias galima spustelėti, todėl skaitytojas gali pereiti prie nurodyto elemento galutiniame HTML.

Yra ir daugiau žymų, pvz., @version, @author, @exception ir kt. Tinkamai naudojamos žymos padeda susieti elementus tarpusavyje ir leidžia lengvai naršyti dokumentacijoje.

„Javadoc“ paleidimas jūsų šaltinio kode

Komandinėje eilutėje iškviečiate Javadoc. Galite paleisti jį atskiruose failuose, ištisuose kataloguose, „Java“ paketuose arba atskirų failų sąraše. Pagal numatytuosius nustatymus „Javadoc“ sugeneruos HTML dokumentacijos failus kataloge, kuriame įvesite komandą. Norėdami gauti pagalbos dėl konkrečių galimų komandų, tiesiog įveskite:

javadoc --padėkite

Norėdami sužinoti, ką tiksliai „Javadoc“ gali padaryti, peržiūrėkite oficialią dokumentaciją Orakulas. Norėdami greitai sukurti dokumentų rinkinį viename faile arba kataloge, galite įvesti javadoc komandų eilutėje, po kurios rašomas failo pavadinimas arba pakaitos simbolis.

javadoc ~/code/failo pavadinimas.java
javadoc ~/code/*.java

Aukščiau yra failų ir katalogų, kuriuos sukūrė „Javadoc“, sąrašas. Kaip matote, jų yra nemažai. Dėl šios priežasties turėtumėte būti tikri, kad paleisdami programą nesate tame pačiame kataloge kaip šaltinio kodas. Taip elgiantis gali susidaryti nemaža netvarka.

Norėdami peržiūrėti naujai sukurtus dokumentus, tiesiog atidarykite index.html failą pageidaujamoje naršyklėje. Gausite tokį puslapį kaip:

Tai vienos trumpos Java klasės dokumentacija, skirta parodyti išvestį. Antraštėje rodomas klasės pavadinimas ir į ją įtraukti metodai. Slenkant žemyn rodomi išsamesni kiekvieno klasės metodo apibrėžimai.

Kaip matote, bet kokio tipo Java projektams, ypač dideliems, turintiems daug tūkstančių kodo eilučių, tokio tipo dokumentacija yra neįkainojama. Būtų sunku sužinoti apie didelę kodų bazę perskaičius jos šaltinio kodą. „Javadoc“ puslapiuose šis procesas yra daug greitesnis ir lengviau sekamas.

„Javadoc“ gali padėti jums tvarkyti „Java“ kodą ir visą susijusią dokumentaciją bei lengvai naudoti. Nesvarbu, ar tai darote dėl savo užmirštamos ateities savęs, ar tam, kad palengvintumėte didelę komandą, „Javadoc“ yra galingas įrankis, galintis pakeisti jūsų „Java“ kodavimo būdą ir sąveiką su juo projektus.

8 geriausi „Java“ tinklaraščiai programuotojams

Skaitykite toliau