Dokumentace javových programů

  • Dokumentace je naprosto nezbytnou součástí javových programů.

  • Rozlišujeme dokumentaci např. instalační, systémovou, uživatelskou, integrační, programátorskou (pro údržbu, rozšiřování)…

  • Zde se budeme věnovat především dokumentaci programátorské, určené těm, kdo budou náš kód využívat ve svých programech, rozšiřovat jej, udržovat jej.

  • Programátorské dokumentaci se říká dokumentace API (apidoc, javadoc).

  • Nejlepším příkladem je přímo dokumentace Java Core API

Pravidla

Při jejím psaní dodržujeme tato pravidla:

  • Dokumentujeme především veřejné (public) a chráněné (protected) prvky (metody, proměnné). Ostatní dle potřeby.

  • Dokumentaci píšeme přímo do zdrojového kódu programu ve speciálních dokumentačních komentářích vpisovaných před příslušné prvky (metody, proměnné).

  • Dovnitř metod píšeme jen pomocné komentáře pro programátory (nebo pro nás samotné).

Typy komentářů

Podobně jako např. v C/C++:

řádkové

od značky // do konce řádku, nepromítnou se do dokumentace API

blokové

začínají /* pak je text komentáře, končí */ na libovolném počtu řádků

dokumentační

od značky /** po značku */ může být opět na libovolném počtu řádků. Každý další řádek může začínat mezerami či *, hvězdička se v komentáři neprojeví.

Kde uvádíme dokumentační komentáře

Dokumentační komentáře uvádíme:

  • Před hlavičkou třídy - pak komentuje třídu jako celek.

  • Před hlavičkou metody nebo proměnné - pak komentuje příslušnou metodu nebo proměnnou.

  • Celý balík (package) je možné komentovat speciálním samostatným HTML souborem package-summary.html uloženým v adresáři balíku.

Generování dokumentace

  • Dokumentace má standardně podobu HTML stránek (s rámy i bez).

  • Dokumentace je generována nástrojem javadoc z

    • dokumentačních komentářů

    • i ze samotného zdrojového textu Lze tedy (základním způsobem) dokumentovat i program bez vložených komentářů!

  • Chování javadoc můžeme změnit

    • volbami (options) při spuštění,

    • použitím jiného tzv. doclet u, což je třída implementující potřebné metody pro generování komentářů.

Značky javadoc

javadoc můžeme podrobněji instruovat pomocí značek vkládaných do dokumentačních komentářů, např.:

@author

specifikuje autora API/programu

@version

označuje verzi API, např. 1.0

@deprecated

informuje, že prvek je zavrhovaný

@exception

popisuje informace o výjimce, kterou metoda propouští ("vyhazuje")

@param

popisuje jeden parametr metody

@since

uvedeme, od kdy (od které verze pg.) je věc podporována/přítomna

@see

uvedeme odkaz, kam je také doporučeno nahlédnout (související věci)

Příklad zdrojového textu se značkami javadoc

Zdrojový text třídy Window:

/**
 * Klasse, die ein Fenster auf dem Bildschirm repräsentiert
 * Konstruktor zum Beispiel:
 * <pre>
 * Window win = new Window(parent);
 * win.show();
 * </pre>
 *
 * @see awt.BaseWindow
 * @see awt.Button
 * @version 1.2 31 Jan 1995
 * @author Bozo the Clown
 **/
 class Window extends BaseWindow { ... }

Příklad dokumentačního komentáře k proměnné:

/**
 * enthält die aktuelle Anzahl der Elemente.
 * muss positiv und kleiner oder gleich der Kapazität sein
 **/
 protected int count;

Tyto a další příklady a odkazy lze vidět v původním materiálu JavaStyleGuide des IGE, odkud byly ukázky převzaty.

Spouštění javadoc

javadoc [options] [packagenames] [sourcefiles] [classnames] [@files]

Možné volby:

  • -help , -verbose

  • -public , -protected , -package , -private - specifikuje, které prvky mají být v dokumentaci zahrnuty (implicitně: -protected)

  • -d destinationdirectory - kam se má dok. uložit

  • -doctitle title - titul celé dokumentace

Konvence pro psaní komentářů

Doporučení Sun/Oracle k psaní dokumentačních komentářů — How to Write Doc Comments for the Javadoc Tool