Dokumenteerige oma Java kood automaatselt Javadociga

Kui teete mis tahes programmeerimist, teate hästi, et üks tüütumaid ülesandeid on koodi dokumenteerimine. Olenemata sellest, kas see on veidi tüütu või ettevõtmine, mille ees on täielik hirm, on koodide dokumenteerimine hädavajalik. Teised peavad mõistma, kuidas teie kood töötab, ja võite isegi olla üks neist, kui loete seda hiljem!

Java pakub probleemile mugavalt sisseehitatud lahendust: Javadoc.

Javadoc aitab teil koodi automaatselt dokumenteerida

Loodetavasti te juba jälgite head kodeerimistavad ja lisage oma koodi selgitavad kommentaarid. Kuigi seda tüüpi koodisisene kommenteerimine on kindlasti kasulik, ei anna see tegelikult midagi käsiraamatuga võrreldavat.

Muidugi saab teine ​​programmeerija teie koodi läbi vaadata ja lugeda konkreetsete klasside, meetodite ja funktsioonide kohta, mis tema ees on. Siiski on äärmiselt raske saada head ülevaadet kogu koodist või leida funktsioone, mis võiksid olla kasulikud, kui te ei tea nende olemasolust. Javadoci eesmärk on see probleem lahendada.

Javadoc loob kogu teie koodi jaoks automaatselt üksikasjaliku ja lugejasõbraliku HTML-juhendi. Mis kõige parem, see teeb seda koodikommentaaride abil, mida tõenäoliselt juba kirjutate.

Mis täpselt on Javadoc ja kuidas see töötab?

Javadoc on eraldiseisev programm, mis on komplektis Oracle'i Java arenduskomplekti (JDK) väljalasetega. Tegelikult ei saa te seda eraldi alla laadida. Kui laadite alla ja installige üks Oracle'i JDK versioonidest, installib see ka Javadoci.

Selle käivitamisel genereerib Javadoc teie Java lähtekoodi spetsiaalselt vormindatud kommentaaridest HTML-dokumentatsiooni. See protsess loob kasulikumat ja loetavamat dokumentatsiooni, julgustades samas ka parimaid tavasid.

Lühidalt, Javadoc võimaldab teil kirjutada koodi ja selle dokumentatsiooni korraga. See lihtsustab teie töövoogu ja võimaldab teil oma aega tõhusamalt kasutada.

Javadoc parsib teie koodis olevaid spetsiaalselt vormindatud kommentaare ja teisendab need HTML-väljundiks. Ainus muudatus, mida peate tõesti tegema, on lisada oma kommentaaridesse teatud stringid. Need annavad Javadocile teada, mida soovite lõppdokumentatsiooni lisada.

Javadoci kommentaarid peaksid vahetult eelnema klassi, välja, konstruktori või meetodi deklaratsioonile. Kommentaar ise peaks:

• Alustage kolme tegelasega /**.
• Lisage iga uue rea algusesse tärn.
• Sulgege kahe tähemärgiga */.

Kommentaarides saate lisada lõppväljundisse HTML-i ja lisada silte, mis loovad lingid teie koodibaasi asjakohastele osadele. Võite isegi kasutada selliseid asju nagu HTML-i pildisildid, et lisada pilte lõplikku dokumentatsiooni. Kui olete vormingu ja saadaolevate siltidega harjunud, on selliste kommentaaride kirjutamine imelihtne.

Siin on näide lihtsate Javadoci kommentaaride illustreerimiseks, mis kirjeldavad funktsiooni, mis võtab URL-ist pildi ja prindib selle ekraanile. Kommentaar eelneb vahetult funktsioonile ja kirjeldab, mida see teeb. See kommentaariplokk kasutab ka kolme jaotisepõhist silti: @param, @tagasi, ja @vaata.

/**
* Tagastab pildiobjekti, mille saab seejärel ekraanile maalida.
* URL-i argument peab määrama absoluutse väärtuse {@link URL}. Nimi
* argument on url-i argumendiga seotud täpsustaja.
* 

* See meetod tagastab alati kohe, olenemata sellest, kas
* pilt on olemas. Millal see aplet üritab pilti joonistada
* ekraan, andmed laaditakse. Graafika primitiivid
* mis joonistavad pilti, värvivad ekraanile järk-järgult.
*
* @param url absoluutne URL, mis annab pildi põhiasukoha
* @param nimetage pildi asukoht URL-i argumendi suhtes
* @tagasi pilt määratud URL-il
* @vaata Pilt
*/
avalik Pilt hanki pilt(URL-i URL, stringi nimi){
proovige {
tagasi getImage(uus URL(url, nimi));
 } püüda (ValformedURLException e) {
tagasinull;
 }
}

Kui Javadoc ülaltoodud koodi töötleb, loob see järgmisega sarnase veebilehe:

Brauser renderdab Javadoci väljundit samamoodi nagu mis tahes HTML-dokumenti. Javadoc ignoreerib täiendavaid tühikuid ja reavahetusi, välja arvatud juhul, kui kasutate selle tühiku loomiseks HTML-märgendeid.

Kommentaari lõpus kasutatavad @sildid genereerivad Parameetrid, Tagastab, ja Vaata ka jaotised, mida näete.

Peaksite järgima @param silt parameetri nime, tühiku ja kirjeldusega. Ülaltoodud juhul on kaks parameetrit: url ja nimi. Pange tähele, et mõlemad kuvatakse dokumentatsiooni väljundis sama pealkirja Parameetrid all. Saate loetleda nii palju parameetreid, kui on kirjeldatava funktsiooni või meetodi jaoks vajalik.

The @tagasi Tag dokumenteerib väärtuse, mille funktsioon tagastab, kui üldse. Olenevalt asjaoludest võib see olla lihtne ühesõnaline kirjeldus või mitu lauset.

The @vaata silt võimaldab teil märgistada muid seotud või asjakohaseid funktsioone. Sel juhul viitab @see silt teisele funktsioonile, mida nimetatakse lihtsalt pildiks. Pange tähele, et selle märgendiga tehtud viited on klõpsatavad lingid, mis võimaldavad lugejal liikuda lõplikus HTML-is viidatud üksuse juurde.

Saadaval on rohkem silte, nagu @version, @author, @exception ja teised. Õige kasutamise korral aitavad sildid üksusi omavahel seostada ja võimaldavad hõlpsasti dokumentatsioonis navigeerida.

Javadoci käivitamine teie lähtekoodil

Javadoci käivitate käsureal. Saate seda käitada üksikutes failides, tervetes kataloogides, Java-pakettides või üksikute failide loendis. Vaikimisi loob Javadoc HTML-i dokumentatsioonifailid kataloogis, kuhu käsu sisestate. Konkreetsete saadaolevate käskude kohta abi saamiseks sisestage lihtsalt:

javadoc -- aidake

Et näha täpsemalt, mida Javadoc saab teha, vaadake ametlikku dokumentatsiooni Oraakel. Sisestage ühe faili või kataloogi jaoks kiire dokumentatsioonikomplekti loomiseks javadoc käsureal, millele järgneb failinimi või metamärk.

javadoc ~/code/failinimi.java
javadoc ~/code/*.java

Ülal on Javadoci loodud failide ja kataloogide loend. Nagu näete, on neid üsna palju. Sel põhjusel peaksite programmi käivitamisel olema kindel, et te ei asu lähtekoodiga samas kataloogis. See võib tekitada korraliku segaduse.

Äsja loodud dokumentide vaatamiseks avage lihtsalt index.html faili oma eelistatud brauseris. Saate järgmise lehe:

See on ühe lühikese Java-klassi dokumentatsioon väljundi demonstreerimiseks. Päis näitab nii klassi nime kui ka selles sisalduvaid meetodeid. Allapoole kerimisel näete iga klassimeetodi üksikasjalikumat määratlust.

Nagu näete, on seda tüüpi dokumentatsioon hindamatu igat tüüpi Java-projektide jaoks, eriti suurte, tuhandete koodiridadega projektide jaoks. Suure koodibaasi tundmaõppimine selle lähtekoodi läbi lugedes oleks väljakutse. Javadoci lehed muudavad selle protsessi palju kiiremaks ja hõlpsamini jälgitavaks.

Javadoc aitab teil hoida Java koodi ja kogu asjakohast dokumentatsiooni korrastatuna ja hõlpsasti kasutatavana. Olenemata sellest, kas teete seda oma unustava tuleviku nimel või selleks, et suure meeskonna jaoks asjad lihtsamaks teha, Javadoc on võimas tööriist, mis võib muuta teie Java-koodi kirjutamise ja sellega suhtlemise viisi projektid.

8 parimat Java-blogi programmeerijatele

Loe edasi