Документирайте вашия Java код автоматично с Javadoc

Ако правите някакъв вид програмиране, ще сте наясно, че една от най-досадните задачи е документирането на вашия код. Независимо дали го намирате за леко досадно или за начинание, пред което се сблъсквате с абсолютен страх, документацията за код е от съществено значение. Други трябва да разберат как работи вашият код и вие може дори да сте един от тях, ако го четете на по-късна дата!

Java удобно предоставя вградено решение на проблема: Javadoc.

Javadoc може да ви помогне да документирате кода си автоматично

Надяваме се, че вече следвате добри практики за кодиране и включете обяснителни коментари във вашия код. Въпреки че този тип коментиране в код със сигурност е полезен, той всъщност не предоставя нищо сравнимо с ръководство.

Разбира се, друг програмист може да разгледа вашия код и да прочете за конкретните класове, методи и функции, които са пред него. Изключително трудно е обаче да получите добър преглед на целия код или да намерите функции, които биха били полезни, когато не знаете, че съществуват. Javadoc има за цел да реши този проблем.

Javadoc автоматично ще генерира подробно и лесно за четене HTML ръководство за целия ви код. Най-хубавото е, че го прави, като използва кодови коментари, които вероятно вече пишете.

Какво точно е Javadoc и как работи?

Javadoc е самостоятелна програма, която идва в комплект с изданията на комплекта за разработка на Java (JDK) на Oracle. Всъщност не можете да го изтеглите отделно. Когато изтеглите и инсталирайте една от версиите на JDK на Oracle, той също така ще инсталира Javadoc.

Когато го стартирате, Javadoc генерира HTML документация от специално форматирани коментари във вашия изходен код на Java. Този процес създава по-полезна и четлива документация, като същевременно насърчава най-добрите практики.

Накратко, Javadoc ви дава възможност да пишете своя код и документацията му едновременно. Това опростява работния ви процес и ви позволява да използвате по-ефективно времето си.

Javadoc работи, като анализира специално форматирани коментари във вашия код и ги преобразува в HTML изход. Единствената промяна, която наистина трябва да направите, е да включите определени низове в коментарите си. Те уведомяват Javadoc какво искате да включите в окончателната документация.

Коментарите в Javadoc трябва непосредствено да предхождат декларация на клас, поле, конструктор или метод. Самият коментар трябва:

• Започнете с трите знака /**.
• Включете звездичка в началото на всеки нов ред.
• Затворете с двата знака */.

В рамките на коментарите можете да включите HTML в крайния изход и да включите тагове, които ще генерират връзки към съответните части от вашата кодова база. Можете дори да използвате неща като HTML маркери за изображения, за да включите изображения в окончателната документация. След като свикнете с формата и наличните тагове, писането на такива коментари е лесно.

Ето пример за илюстриране на прости коментари в Javadoc, описващи функция, която получава изображение от URL и го отпечатва на екрана. Коментарът непосредствено предхожда функцията и описва какво прави. Този блок за коментари също използва три специфични за раздел маркера: @param, @връщане, и @виж.

/**
* Връща обект на изображение, който след това може да бъде нарисуван на екрана.
* Аргументът url трябва да указва абсолютно {@link URL}. Името
* аргументът е спецификатор, който е относителен към аргумента url.
* 

* Този метод винаги се връща незабавно, независимо дали е или не
* изображение съществува. Кога това аплет се опитва да нарисува изображението
* на екрана, данните ще бъдат заредени. Графичните примитиви
* които рисуват изображението постепенно ще рисуват на екрана.
*
* @param url абсолютен URL, даващ основното местоположение на изображението
* @param назовете местоположението на изображението спрямо аргумента url
* @връщане изображението на посочения URL адрес
* @виж Образ
*/
обществено Образ getImage(URL URL, име на низ){
опитвам {
връщане getImage(нов URL (URL, име));
 } улов (MalformedURLEException e) {
връщаненула;
 }
}

Когато Javadoc обработва кода по-горе, той генерира уеб страница, подобна на следната:

Браузърът изобразява изхода на Javadoc по същия начин, по който показва всеки HTML документ. Javadoc игнорира допълнителни бели интервали и прекъсвания на редове, освен ако не използвате HTML тагове, за да създадете това пространство.

@tags, използвани в края на коментара, генерират Параметри, Се завръща, и Вижте също секции, които виждате.

Трябва да следвате @param таг с името на параметъра, интервал и описанието му. В горния случай има два параметъра: url и име. Забележете, че и двете се появяват под едно и също заглавие на параметри в изхода на документацията. Можете да изброите толкова параметри, колкото са необходими за функцията или метода, който описвате.

В @връщане tag документира стойността, която функцията връща, ако изобщо. Това може да бъде просто описание от една дума или много изречения, в зависимост от обстоятелствата.

В @виж tag ви позволява да маркирате други функции, които са свързани или релевантни. В този случай маркерът @see се отнася до друга функция, наречена просто Image. Имайте предвид, че препратките, направени с този маркер, са връзки с възможност за щракване, което позволява на читателя да прескочи до посочения елемент в крайния HTML.

Има още налични маркери като @version, @author, @exception и други. Когато се използват правилно, етикетите помагат за свързването на елементите един с друг и правят възможно лесното навигиране в документацията.

Изпълняване на Javadoc на вашия изходен код

Извиквате Javadoc от командния ред. Можете да го стартирате на единични файлове, цели директории, java пакети или в списък с отделни файлове. По подразбиране Javadoc ще генерира файловете с HTML документация в директорията, където въвеждате командата. За да получите помощ за конкретните налични команди, просто въведете:

javadoc --помогне

За да видите какво точно може да прави Javadoc по-подробно, вижте официалната документация от Оракул. За да създадете бърз набор от документация за един файл или директория, можете да въведете javadoc на командния ред, последван от име на файл или заместващ знак.

javadoc ~/code/име на файл.java
javadoc ~/code/*.java

По-горе е списък на файловете и директориите, създадени от Javadoc. Както можете да видите, има доста от тях. Поради тази причина трябва да сте сигурни, че не сте в същата директория като вашия изходен код, когато стартирате програмата. Това може да създаде доста бъркотия.

За да видите новосъздадените си документи, просто отворете index.html файл в предпочитания от вас браузър. Ще получите страница като следната:

Това е документацията за един кратък Java клас за демонстриране на изхода. Заглавката показва името на класа, както и методите, включени в него. Превъртането надолу разкрива по-подробни дефиниции на всеки от методите на класа.

Както можете да видите, за всеки тип Java проекти, особено големи с много хиляди редове код, този тип документация е безценна. Би било предизвикателство да научите за голяма кодова база, като прочетете нейния изходен код. Страниците на Javadoc правят този процес много по-бърз и лесен за следване.

Javadoc може да ви помогне да поддържате вашия Java код и цялата съответна документация организирани и лесни за използване. Независимо дали го правите за вашето забравящо бъдещо аз или за да улесните нещата за голям екип, Javadoc е мощен инструмент, който може да промени начина, по който пишете и взаимодействате с вашето Java кодиране проекти.

8-те най-добри блога на Java за програмисти

Прочетете Следващото