Аутоматски документујте свој Јава код помоћу Јавадоц-а

Ако радите било какву врсту програмирања, бићете свесни да је један од најдосаднијих задатака документовање вашег кода. Без обзира да ли сматрате да је то мало досадно или је подухват са којим се потпуно ужасавате, документација кода је неопходна. Други треба да разумеју како ваш код функционише, а можда ћете чак и бити један од њих ако га касније будете читали!

Јава згодно пружа уграђено решење проблема: Јавадоц.

Јавадоц вам може помоћи да аутоматски документујете свој код

Надамо се да већ пратите добре праксе кодирања и укључите коментаре са објашњењима у свој код. Иако је ова врста коментара у коду свакако корисна, она заправо не пружа ништа упоредиво са приручником.

Наравно, други програмер може да прегледа ваш код и прочита о специфичним класама, методама и функцијама које су пред њим. Међутим, изузетно је тешко добити добар преглед целог кода или пронаћи функције које би могле бити корисне када не знате да постоје. Јавадоц има за циљ да реши тај проблем.

Јавадоц ће аутоматски генерисати детаљан и разумљив ХТМЛ приручник за сав ваш код. Најбоље од свега, то ради коришћењем коментара кода које вероватно већ пишете.

Шта је заправо Јавадоц и како функционише?

Јавадоц је самостални програм који долази у пакету са издањима Орацле Јава развојног комплета (ЈДК). У ствари, не можете га преузети засебно. Када преузмете и инсталирајте једну од Орацлеових ЈДК верзија, такође ће инсталирати Јавадоц.

Када га покренете, Јавадоц генерише ХТМЛ документацију из посебно форматираних коментара у вашем Јава изворном коду. Овај процес ствара кориснију, читљивију документацију, а истовремено подстиче најбоље праксе.

Укратко, Јавадоц вам омогућава да истовремено напишете свој код и његову документацију. То поједностављује ваш радни ток и омогућава вам да ефикасније користите своје време.

Јавадоц ради тако што анализира посебно форматиране коментаре у вашем коду и конвертује их у ХТМЛ излаз. Једина промена коју заиста треба да направите је да укључите одређене низове у своје коментаре. Ово Јавадоц-у даје до знања шта желите да укључите у коначну документацију.

Јавадоц коментари треба да претходе декларацији класе, поља, конструктора или метода. Сам коментар треба да:

• Почните са три лика /**.
• Укључите звездицу на почетак сваког новог реда.
• Затворите са два лика */.

Унутар коментара можете укључити ХТМЛ у коначни резултат и укључити ознаке које ће генерисати везе до релевантних делова ваше базе кода. Можете чак користити ствари као што су ХТМЛ ознаке слика да бисте укључили слике у коначну документацију. Када се навикнете на формат и доступне ознаке, писање таквих коментара је лако.

Ево примера за илустрацију једноставних Јавадоц коментара који описују функцију која добија слику са УРЛ-а и штампа је на екрану. Коментар непосредно претходи функцији и описује шта она ради. Овај блок коментара такође користи три ознаке специфичне за одељак: @парам, @ретурн, и @види.

/**
* Враћа објекат слике који се затим може осликати на екрану.
* Аргумент урл мора навести апсолутну вредност {@линк УРЛ}. Име
* аргумент је спецификација која је релативна у односу на аргумент урл.
* 

* Овај метод се увек враћа одмах, без обзира да ли је или не
* слика постоји. Када ово аплет покушава да нацрта слику
* на екрану, подаци ће бити учитани. Графички примитиви
* који цртају слику постепено ће сликати на екрану.
*
* @парам урл апсолутни УРЛ који даје основну локацију слике
* @парам наведите локацију слике у односу на аргумент урл
* @ретурн слику на наведеној УРЛ адреси
* @види Слика
*/
јавности Слика гетИмаге(УРЛ УРЛ, назив стринга){
покушати {
повратак гетИмаге(Нова УРЛ (урл, име));
 } улов (МалформедУРЛЕЕкцептион е) {
повратакнула;
 }
}

Када Јавадоц обради горњи код, генерише веб страницу сличну следећој:

Прегледач приказује Јавадоц излаз на исти начин на који приказује било који ХТМЛ документ. Јавадоц игнорише додатни размак и преломе линија осим ако не користите ХТМЛ ознаке за креирање тог простора.

@ознаке које се користе на крају коментара генеришу Параметерс, Повратак, и Такође видети одељке које видите.

Требало би да пратите @парам таг са именом параметра, размаком и његовим описом. У случају изнад, постоје два параметра: урл и име. Обратите пажњу да се оба појављују под истим насловом Параметри у излазу документације. Можете навести онолико параметара колико је потребно за функцију или метод који описујете.

Тхе @ретурн таг документује вредност коју функција враћа, ако је уопште има. То може бити једноставан опис од једне речи или више реченица, у зависности од околности.

Тхе @види таг вам омогућава да означите друге функције које су повезане или релевантне. У овом случају, ознака @сее се односи на другу функцију која се зове једноставно Слика. Имајте на уму да су референце направљене са овом ознаком везе на које се може кликнути, што омогућава читаоцу да скочи на референцирану ставку у коначном ХТМЛ-у.

Доступно је више ознака као што су @версион, @аутхор, @екцептион и други. Када се правилно користе, ознаке помажу у међусобном повезивању ставки и омогућавају лаку навигацију кроз документацију.

Покретање Јавадоц-а на вашем изворном коду

Позивате Јавадоц на командној линији. Можете га покренути на појединачним датотекама, целим директоријумима, јава пакетима или на листи појединачних датотека. Јавадоц ће подразумевано генерисати датотеке ХТМЛ документације у директоријуму у који унесете команду. Да бисте добили помоћ о одређеним доступним командама, једноставно унесите:

јавадоц --помоћ

Да бисте видели шта тачно Јавадоц може да уради детаљније, погледајте званичну документацију из Орацле. Да бисте креирали брзи скуп документације за једну датотеку или директоријум који можете да унесете јавадоц на командној линији праћено именом датотеке или џокер знаком.

јавадоц ~/code/име датотеке.јава
јавадоц ~/code/*.јава

Изнад је листа датотека и директоријума које је направио Јавадоц. Као што видите, има их доста. Из тог разлога, требало би да будете сигурни да се не налазите у истом директоријуму као и ваш изворни код када покренете програм. То би могло створити прави неред.

Да бисте видели своје новостворене документе, једноставно отворите индек.хтмл датотеку у жељеном претраживачу. Добићете страницу као што је следећа:

Ово је документација за једну, кратку Јава класу која демонстрира излаз. Заглавље приказује назив класе као и методе укључене у њега. Померање надоле открива детаљније дефиниције сваке методе класе.

Као што видите, за било коју врсту Јава пројекта, посебно велике са много хиљада линија кода, ова врста документације је непроцењива. Био би изазов научити о великој бази кода читајући њен изворни код. Јавадоц странице чине овај процес много бржим и лакшим за праћење.

Јавадоц вам може помоћи да ваш Јава код и сву релевантну документацију буде организован и лак за коришћење. Било да то радите за своју заборавну будућност или да бисте олакшали ствари великом тиму, Јавадоц је моћан алат који може да промени начин на који пишете и комуницирате са својим Јава кодирањем пројектима.

8 најбољих Јава блогова за програмере

Реад Нект