PJV16 1 Dokumentace Tvorba dokumentace byla vždy útrpnou záležitostí neboť: programátoři ji krajně neradi dělají - a pokud - tak až nakonec, nebývala žádná.

Prezentace na téma: "PJV16 1 Dokumentace Tvorba dokumentace byla vždy útrpnou záležitostí neboť: programátoři ji krajně neradi dělají - a pokud - tak až nakonec, nebývala žádná."— Transkript prezentace:

1 PJV16 1 Dokumentace Tvorba dokumentace byla vždy útrpnou záležitostí neboť: programátoři ji krajně neradi dělají - a pokud - tak až nakonec, nebývala žádná vodítka jak ji dělat, a byla-li – tak velmi rozmanitá, vytvářená různými technikami, odděleně od popisovaných programů, a na různých nosičích, často neaktuální, obtížně modifikovatelná, těžko dosažitelná nebo dokonce ztracená. Velevýznamným přínosem Javy k metodice programování je také originální způsob podpory dokumentace softwarového díla programem javadoc. Tím se dokumentační utrpení velmi zmírňuje, neboť vnitřní ( technická ) dokumentace je součástí zdrojových souborů, celosvětově stylově jednotná ve tvaru důmyslně provázaných HTML stránek.

2 PJV16 2 javadoc Součástí jdk je také dokumentační program javadoc a jeho popis: jdk.*.*/bin/javadoc jdk.*.*/docs/tooldocs/solaris/javadoc.html jdk.*.*/docs/tooldocs/windows/javadoc.html Pro úplné informace o projektu javadoc: http://www.oracle.com/technetwork/java/javase/documentation/javadoc- 137458.html

3 PJV16 3 javadoc Vstupem do programu javadoc jsou zdrojové soubory, výstupem je adresář obsahující tzv. doclety ve tvaru.html. Programátor píše do zdrojových souborů tzv. dokumentační komentáře ( začínají lomítkem a dvěma hvězdičkami ) a to před popisované části, tj. třídu, interfejs, atribut, metodu a konstruktor. Zavináč vyznačuje tzv. tag pro strukturaci význačných složek. Příklad popisu metody: /** Tato metoda počítá cosi * a nějak. * bla bla bla..... * @param i int * @throws NullPointerException * @return int */ IDE usnadňují psaní těchto komentářů.

4 PJV16 4 javadoc Javadoc je velmi složitý program ( ve verzi j2sdk1.4 má 56 opcí ). Následuje několik jednoduchých možností k vytvoření dokumentace celých balíčků v rámci projektu. Pro spouštění z řádky: javadoc.exe -breakiterator // doporučeno -d projekt\doc // výstupní adresář [ -overview povidani.html ] // do přehledu [ -public | -protected | -private ] // hloubka výběru -sourcepath projekt\src // cesta ke zdrojům [ balik1 balik2... ] // jednotlivé balíčky [ -subpackages // probírat strom balik3 balik4... ] // kořenové balíčky Soubor povidani.htm umožnuje dodat vlastní komentáře, obrázky či dokonce i interaktivní aplety.

5 PJV16 5 Podpora v Netbeans Vytvoření dokumentace balíčku je velmi jednoduché: Run -> Generate Javadoc nebo Project -> Generate Javadoc Dokumentace se vytvoří v distribučním adresáři dist