Dokumentuj swój kod Java automatycznie za pomocą Javadoc

Jeśli zajmujesz się programowaniem, będziesz dobrze wiedział, że jednym z najbardziej żmudnych zadań jest dokumentowanie kodu. Niezależnie od tego, czy uważasz to za nieco irytujące, czy też jest to przedsięwzięcie, z którym mierzysz się z absolutnym strachem, dokumentacja kodu jest niezbędna. Inni muszą zrozumieć, jak działa Twój kod, a nawet możesz być jednym z nich, jeśli będziesz go czytać później!

Java wygodnie zapewnia wbudowane rozwiązanie problemu: Javadoc.

Javadoc może pomóc w automatycznym udokumentowaniu kodu

Mam nadzieję, że już obserwujesz dobre praktyki kodowania i dołącz komentarze wyjaśniające w swoim kodzie. Chociaż ten rodzaj komentowania w kodzie jest z pewnością pomocny, tak naprawdę nie zapewnia niczego porównywalnego z instrukcją.

Oczywiście, inny programista może przejrzeć Twój kod i przeczytać o konkretnych klasach, metodach i funkcjach, które są przed nim. Jednak niezwykle trudno jest uzyskać dobry przegląd całego kodu lub znaleźć funkcje, które mogą być przydatne, gdy nie wiesz o ich istnieniu. Javadoc ma na celu rozwiązanie tego problemu.

Javadoc automatycznie wygeneruje szczegółowy i przyjazny dla czytelnika podręcznik HTML dla całego kodu. Co najlepsze, robi to za pomocą komentarzy do kodu, które prawdopodobnie już piszesz.

Czym dokładnie jest Javadoc i jak to działa?

Javadoc to samodzielny program, który jest dostarczany w pakiecie z wydaniami pakietu Java Development Kit (JDK) firmy Oracle. W rzeczywistości nie można go pobrać osobno. Po pobraniu i zainstaluj jedną z wersji Oracle JDK, zainstaluje również Javadoc.

Po uruchomieniu Javadoc generuje dokumentację HTML ze specjalnie sformatowanych komentarzy w kodzie źródłowym Java. Ten proces tworzy bardziej użyteczną, czytelną dokumentację, jednocześnie zachęcając do najlepszych praktyk.

Krótko mówiąc, Javadoc umożliwia jednoczesne pisanie kodu i dokumentacji. Upraszcza to przepływ pracy i pozwala na bardziej efektywne wykorzystanie czasu.

Javadoc działa na zasadzie analizowania specjalnie sformatowanych komentarzy w kodzie i konwertowania ich na dane wyjściowe HTML. Jedyną zmianą, jaką naprawdę musisz wprowadzić, jest umieszczenie w komentarzach pewnych ciągów. Dzięki temu Javadoc wie, co chcesz uwzględnić w ostatecznej dokumentacji.

Komentarze Javadoc powinny bezpośrednio poprzedzać deklarację klasy, pola, konstruktora lub metody. Sam komentarz powinien:

• Zacznij od trzech znaków /**.
• Dołącz gwiazdkę na początku każdego nowego wiersza.
• Zamknij z dwoma postaciami */.

W komentarzach możesz dołączyć HTML do końcowego wyniku i dołączyć tagi, które będą generować linki do odpowiednich części Twojej bazy kodu. Możesz nawet użyć takich rzeczy, jak znaczniki obrazu HTML, aby dołączyć obrazy do ostatecznej dokumentacji. Gdy przyzwyczaisz się do formatu i dostępnych tagów, pisanie takich komentarzy jest bardzo proste.

Oto przykład ilustrujący proste komentarze Javadoc opisujące funkcję, która pobiera obraz z adresu URL i wyświetla go na ekranie. Komentarz bezpośrednio poprzedza funkcję i opisuje jej działanie. Ten blok komentarzy wykorzystuje również trzy znaczniki specyficzne dla sekcji: @param, @zwrócić, oraz @Widzieć.

/**
* Zwraca obiekt Image, który można następnie namalować na ekranie.
* Argument url musi określać wartość bezwzględną {@połączyć URL}. Imię
* argument jest specyfikatorem odnoszącym się do argumentu url.
* 

* Ta metoda zawsze zwraca się natychmiast, niezależnie od tego, czy
* obraz istnieje. Kiedy ten aplet próbuje narysować obrazek na
* ekran, dane zostaną załadowane. Prymitywy graficzne
* które rysują obraz, będą stopniowo malować na ekranie.
*
* @param url bezwzględny adres URL podający podstawową lokalizację obrazu
* @param nazwij lokalizację obrazu względem argumentu url
* @zwrócić obraz pod podanym adresem URL
* @Widzieć Obraz
*/
publiczny Obraz pobierzobraz(URL, nazwa ciągu){
próbować {
zwrócić pobierzObraz(Nowy URL(url, nazwa));
 } złapać (nieprawidłowy wyjątek adresu URL e) {
zwrócićzero;
 }
}

Kiedy Javadoc przetwarza powyższy kod, generuje stronę podobną do następującej:

Przeglądarka renderuje dane wyjściowe Javadoc w podobny sposób, w jaki wyświetla dowolny dokument HTML. Javadoc ignoruje dodatkowe odstępy i łamania linii, chyba że do utworzenia tej spacji użyjesz znaczników HTML.

@tagi użyte na końcu komentarza generują Parametry, Zwroty, oraz Zobacz też sekcje, które widzisz.

Powinieneś postępować zgodnie z @param tag z nazwą parametru, spacją i jego opisem. W powyższym przypadku mamy do czynienia z dwoma parametrami: adres URL oraz Nazwa. Zauważ, że oba pojawiają się pod tym samym nagłówkiem Parametry w danych wyjściowych dokumentacji. Możesz podać tyle parametrów, ile jest niezbędnych dla opisywanej funkcji lub metody.

The @zwrócić tag dokumentuje wartość zwracaną przez funkcję, jeśli w ogóle. Może to być prosty opis złożony z jednego słowa lub wiele zdań, w zależności od okoliczności.

The @Widzieć tag pozwala oznaczyć inne funkcje, które są powiązane lub istotne. W tym przypadku tag @see odnosi się do innej funkcji zwanej po prostu Image. Pamiętaj, że odwołania utworzone za pomocą tego tagu są linkami, które można kliknąć, umożliwiając czytelnikowi przeskoczenie do elementu, do którego prowadzi odwołanie w końcowym kodzie HTML.

Dostępnych jest więcej tagów, takich jak @version, @author, @exception i inne. Przy odpowiednim użyciu tagi pomagają powiązać elementy ze sobą i umożliwiają łatwe poruszanie się po dokumentacji.

Uruchamianie Javadoc w kodzie źródłowym

Wywołujesz Javadoc w wierszu poleceń. Możesz go uruchomić na pojedynczych plikach, całych katalogach, pakietach java lub na liście pojedynczych plików. Domyślnie Javadoc wygeneruje pliki dokumentacji HTML w katalogu, w którym wprowadzisz polecenie. Aby uzyskać pomoc na temat konkretnych dostępnych poleceń, wystarczy wpisać:

javadoc --Wsparcie

Aby zobaczyć, co dokładnie może zrobić Javadoc, zapoznaj się z oficjalną dokumentacją od Wyrocznia. Aby utworzyć szybki zestaw dokumentacji na pojedynczym pliku lub katalogu, możesz wejść javadoc w wierszu poleceń, po którym następuje nazwa pliku lub symbol wieloznaczny.

javadoc ~/code/nazwapliku.java
javadoc ~/code/*.Jawa

Powyżej znajduje się lista plików i katalogów utworzonych przez Javadoc. Jak widać, jest ich sporo. Z tego powodu powinieneś upewnić się, że nie znajdujesz się w tym samym katalogu, co kod źródłowy, kiedy uruchamiasz program. Mogłoby to narobić bałaganu.

Aby wyświetlić nowo utworzone dokumenty, po prostu otwórz index.html plik w preferowanej przeglądarce. Otrzymasz stronę podobną do następującej:

To jest dokumentacja dla pojedynczej, krótkiej klasy Java, aby zademonstrować wyniki. Nagłówek pokazuje nazwę klasy oraz zawarte w niej metody. Przewijanie w dół ujawnia bardziej szczegółowe definicje każdej z metod klasy.

Jak widać, dla każdego typu projektu Java, szczególnie dużego z wieloma tysiącami linijek kodu, ten rodzaj dokumentacji jest nieoceniony. Wyzwaniem byłoby poznanie dużej bazy kodu poprzez przeczytanie jej kodu źródłowego. Strony Javadoc znacznie przyspieszają i ułatwiają śledzenie tego procesu.

Javadoc może pomóc w uporządkowaniu i łatwej obsłudze kodu Java i całej odpowiedniej dokumentacji. Niezależnie od tego, czy robisz to dla swojej zapominalskiej przyszłości, czy dla ułatwienia pracy dużego zespołu, Javadoc to potężne narzędzie, które może zmienić sposób pisania i interakcji z kodowaniem Java projektowanie.

8 najlepszych blogów Java dla programistów

Czytaj dalej