Dokumentujte svůj kód Java automaticky pomocí Javadoc

Pokud děláte jakýkoli druh programování, budete si dobře vědomi toho, že jedním z nejnudnějších úkolů je dokumentace vašeho kódu. Ať už to považujete za mírně otravné nebo jako podnik, kterému čelíte absolutní hrůzy, dokumentace kódu je nezbytná. Ostatní musí rozumět tomu, jak váš kód funguje, a vy můžete být jedním z nich, pokud jej budete číst později!

Java pohodlně poskytuje vestavěné řešení problému: Javadoc.

Javadoc vám může pomoci zdokumentovat váš kód automaticky

Doufám, že už sledujete dobré kódovací postupy a zahrňte do kódu vysvětlující komentáře. I když je tento typ komentářů v kódu jistě užitečný, ve skutečnosti neposkytuje nic srovnatelného s manuálem.

Jistě, jiný programátor si může prohlédnout váš kód a přečíst si o konkrétních třídách, metodách a funkcích, které má před sebou. Je však extrémně obtížné získat dobrý přehled o celém kódu nebo najít funkce, které by mohly být užitečné, když nevíte, že existují. Javadoc se snaží tento problém vyřešit.

Javadoc automaticky vygeneruje podrobný a čtenářsky přívětivý HTML manuál pro veškerý váš kód. Nejlepší ze všeho je, že to dělá pomocí komentářů ke kódu, které pravděpodobně již píšete.

Co přesně je Javadoc a jak to funguje?

Javadoc je samostatný program, který je dodáván s verzemi Oracle Java Development Kit (JDK). Ve skutečnosti si jej nemůžete stáhnout samostatně. Když si stáhnete a nainstalovat jednu z verzí Oracle JDK, nainstaluje také Javadoc.

Když jej spustíte, Javadoc vygeneruje dokumentaci HTML ze speciálně formátovaných komentářů ve zdrojovém kódu Java. Tento proces vytváří užitečnější a čitelnější dokumentaci a zároveň podporuje osvědčené postupy.

Stručně řečeno, Javadoc vám umožňuje psát váš kód a jeho dokumentaci současně. Zjednodušuje váš pracovní postup a umožňuje efektivněji využívat váš čas.

Javadoc funguje tak, že analyzuje speciálně formátované komentáře ve vašem kódu a převádí je na výstup HTML. Jedinou změnou, kterou skutečně musíte provést, je zahrnout do komentářů určité řetězce. Díky nim Javadoc ví, co chcete zahrnout do finální dokumentace.

Komentáře Javadoc by měly bezprostředně předcházet deklaraci třídy, pole, konstruktoru nebo metody. Samotný komentář by měl:

• Začněte třemi postavami /**.
• Na začátek každého nového řádku vložte hvězdičku.
• Zavřete dvěma postavami */.

V rámci komentářů můžete zahrnout HTML do konečného výstupu a zahrnout značky, které vygenerují odkazy na relevantní části vaší kódové základny. K zahrnutí obrázků do konečné dokumentace můžete dokonce použít věci, jako jsou značky obrázků HTML. Jakmile si zvyknete na formát a dostupné tagy, psaní takových komentářů je hračka.

Zde je příklad pro ilustraci jednoduchých komentářů Javadoc popisujících funkci, která získá obrázek z adresy URL a vytiskne jej na obrazovku. Komentář bezprostředně předchází funkci a popisuje, co dělá. Tento blok komentářů také využívá tři značky specifické pro sekci: @param, @vrátit se, a @vidět.

/**
* Vrátí objekt obrázku, který lze poté nakreslit na obrazovku.
* Argument url musí uvádět absolutní hodnotu {@odkaz URL}. Název
* argument je specifikátor, který je relativní k argumentu url.
* 

* Tato metoda se vždy vrátí okamžitě, bez ohledu na to, zda
*obrázek existuje. Když tento applet se pokouší nakreslit obrázek
* na obrazovce, data se načtou. Grafická primitiva
*, které kreslí obrázek, se postupně vybarví na obrazovku.
*
* @param url absolutní URL udávající základní umístění obrázku
* @param pojmenujte umístění obrázku vzhledem k argumentu url
* @vrátit se obrázek na zadané adrese URL
* @vidět obraz
*/
veřejnost obraz getImage(URL URL, název řetězce){
Snaž se {
vrátit se getImage(Nový URL(url, název));
 } úlovek (MalformedURLException e) {
vrátit senula;
 }
}

Když Javadoc zpracuje výše uvedený kód, vygeneruje webovou stránku podobnou následujícímu:

Prohlížeč vykresluje výstup Javadoc v podstatě stejným způsobem, jakým zobrazuje jakýkoli dokument HTML. Javadoc ignoruje nadbytečné bílé znaky a konce řádků, pokud k vytvoření tohoto prostoru nepoužijete značky HTML.

@tagy použité na konci komentáře generují Parametry, Návraty, a Viz také sekce, které vidíte.

Měli byste se řídit @param tag s názvem parametru, mezerou a jeho popisem. Ve výše uvedeném případě existují dva parametry: url a název. Všimněte si, že oba se ve výstupu dokumentace objeví pod stejným nadpisem Parametry. Můžete uvést tolik parametrů, kolik je nezbytné pro funkci nebo metodu, kterou popisujete.

The @vrátit se tag dokumentuje hodnotu, kterou funkce vrací, pokud vůbec. Může to být jednoduchý jednoslovný popis nebo mnoho vět, podle okolností.

The @vidět tag umožňuje označit další funkce, které souvisejí nebo jsou relevantní. V tomto případě značka @see odkazuje na další funkci nazvanou jednoduše Image. Upozorňujeme, že odkazy provedené pomocí této značky jsou klikatelné odkazy, které umožňují čtenáři přejít na odkazovanou položku ve finálním HTML.

K dispozici je více značek, například @version, @author, @exception a další. Při správném použití pomáhají štítky vzájemně propojovat položky a umožňují snadnou navigaci v dokumentaci.

Spuštění Javadocu ve zdrojovém kódu

Javadoc vyvoláte na příkazovém řádku. Můžete jej spustit na jednotlivých souborech, celých adresářích, balících Java nebo přes seznam jednotlivých souborů. Ve výchozím nastavení Javadoc vygeneruje soubory HTML dokumentace v adresáři, do kterého zadáte příkaz. Chcete-li získat nápovědu ke konkrétním dostupným příkazům, jednoduše zadejte:

javadoc --Pomoc

Chcete-li vidět, co přesně Javadoc umí, podrobněji se podívejte na oficiální dokumentaci Věštec. Chcete-li vytvořit rychlou sadu dokumentace o jediném souboru nebo adresáři, můžete zadat javadoc na příkazovém řádku následovaný názvem souboru nebo zástupným znakem.

javadoc ~/code/název_souboru.java
javadoc ~/code/*.Jáva

Výše je seznam souborů a adresářů, které Javadoc vytvořil. Jak vidíte, je jich poměrně dost. Z tohoto důvodu byste si měli být jisti, že se při spuštění programu nenacházíte ve stejném adresáři jako váš zdrojový kód. Mohlo by to způsobit pořádný nepořádek.

Chcete-li zobrazit nově vytvořené dokumenty, jednoduše otevřete soubor index.html soubor ve vašem preferovaném prohlížeči. Získáte stránku jako je následující:

Toto je dokumentace pro jedinou krátkou třídu Java, která demonstruje výstup. Záhlaví zobrazuje název třídy a také metody, které jsou v ní obsaženy. Posouváním dolů odhalíte podrobnější definice každé z metod třídy.

Jak vidíte, pro jakýkoli typ projektu Java, zejména pro velké projekty s mnoha tisíci řádky kódu, je tento typ dokumentace neocenitelný. Bylo by náročné dozvědět se o velké kódové základně čtením jejího zdrojového kódu. Stránky Javadoc tento proces mnohem rychleji a snadněji sledují.

Javadoc vám pomůže udržet váš kód Java a veškerou relevantní dokumentaci organizovanou a snadno použitelnou. Ať už to děláte pro své zapomnětlivé budoucí já nebo pro usnadnění práce velkému týmu, Javadoc je výkonný nástroj, který může změnit způsob psaní a interakce s vaším kódováním Java projekty.

8 nejlepších Java blogů pro programátory

Přečtěte si další