JavaDoc - příkazová řádka - Builder.cz - Informacni server o programovani

Navigace:  » Úvodní stránka  » Rubriky  » Java  

21. prosince 2001, 00.00 | Dnes to bude řekněme opět kompletní průvodce parametry příkazové řádky JavaDocu. Po minulých dílech: úvodu a kompletním průvodci
tagy se dostáváme do úplného finále našeho seriálu.

V tomto posledním dílu seriálu se budeme věnovat příkazové řádce samotného JavaDocu.

Jak již bylo řečeno v prvním dílu seriálu, JavaDoc lze spouštět s parametry jednotlivých souborů, které se mají zpracovat.

javadoc myProg.java rem či javadoc *.java

Javadoc používá pro definování výstupu doclety. Pokud nespecifikujete jinak, JavaDoc používá svůj - defaultní. Vlastní definice docletu se pak provádí s parametrem -doclet. Příkazový řádek s tímto parametrem pak může obsahovat další parametry zmíněné pod tímto textem. Malá poznámčička: vzhledem k tomu, že Java má blíže Unixu než Windows, tak příkazová řádka je citlivá na velikost písmen!

Seznam jednotlivých parametrů

-1.1 (verze < 1.4) -author -bootclasspath -bottom -charset -classpath -d -docencoding -doclet -docletpath -doctitle -encoding -extdirs -footer -group -header -help -helpfile -J -link -linkoffline

-locale -nodeprecated -nodeprecatedlist -nohelp -noindex -nonavbar -notree -overview -package -private -protected -public -serialwarn -sourcepath -splitindex -stylesheetfile -title -use -verbose -version -windowtitle

Rád bych připomněl, že jednotlivé zde zmíněné parametry dají "libovolně" kombinovat a shlukovat do skupin. Takže výsledný příkazový řádek může být dosti dlouhý. Proto bych raději doporučil si vytvořit BAT soubor a do něj napsat daný příkaz. Už jen proto, že se zde lépe opravují překlepy, ale hlavně až budete chtít vytvořit dokumentaci příště, nemusíte nic psát, jen spustíte již vytvoření skript.

Nyní si projdeme detailněji jednotlivé volby, příkazové řádky. Pojedeme přesně podle toho jak to vypisuje JavaDoc.

-overview cesta\soubor

Zadaný soubor se vloží do souboru "overview-sumary.html". Typicky by se to dalo použít, když chcete umístit tohoto souboru obsah do nadřazeného adresáře. Cesta resp. jméno souboru může být relativní - odvozená od cesty specifikované v parametru -sourcepath.

-public

zobrazí public třídy a členy.

-protected

zobrazí jen protected a public třídy a členy. Tento parametr je jako defaultní.

-package

zobrazí pouze balík, protected, public třídy a členy.

-private

zobrazí všechny třídy a členy.

-help

zobrazí nápovědu příkazové řádky. To co vypisuje na obrazovku, několik stránek, si zde můžete stáhnout jako textový soubor.

-doclet třída

označení třídy, kterou JavaDoc používá pro generování dokumentů. V této třídě je definován obsah a výstupní formuláře. Jestliže jste tento parametr nezadali, pak JavaDoc používá svůj defaultní doclet (výstup do HTML). Doclet musí obsahovat metodu start(Root).
Poznámka: cesta k docletu se definuje následujícím parametrem.

-docletpath cesta_docletu

určuje cestu k souboru třídy docletu, která je určena parametrem -doclet. Nemusíte ji uvádět, pokud doclet je v prohledávané cestě.

-1.1 (verze < 1.4)

tento parametr slouží pro vytvoření dokumentace ve stylu Javy verze 1.1. Měla by vypadat stejně a být i stejně funkční. Uvidíte sami, spíše neuvidíte, protože tento formát již nepodporuje verze 1.4. Je tady ještě jeden problém, ne všechny parametry jsou zde podporovány, takže vám nezbude nic jiného než se podívat do nápovědy:

javadoc -1.1 -help

-sourcepath zdrojová_cesta

určuje cestu/cesty, kde se mají hledat java soubory. Je to stejné jako u příkazu javac. Pro ty, kdož to neznají, připomenu, že jednotlivé cesty se oddělují ;.

Tato cesta je pak kořenová pro vytvořenou dokumentaci.

javadoc -sourcepath C:\projekty\booklet *.java

-classpath cesta

absolutně stejné nastavení jako classpath u javac. Zadáte cestu / cesty, kde se mají hledat class soubory.

javadoc -classpath \projekty\booklet\lib -sourcepath \projekty\booklet\src com.booklet

Classpath není nutno uvádět pokud ji máte nastavenou jako proměnou systému. A pokud ani to nemáte, tak JavaDoc prohledává aktuální adresáře :-), což potažmo platí i sourcepath.

-bootclasspath cesta

nastavení cestky, kde "boot" třídy. Normálně tyto třídy jsou umístěny v instalaci Javy a není nutno toto nastavení měnit - nastavovat.

-extdirs adresář

Určení adresáře, ve kterém jsou rozšiřující třídy. Tyto třídy pak používají Java Extension mechanism. ExtDirs je částí cesty (-classpath), kterou prohledává JavaDoc, když hledá zdrojové a class soubory. Stejně jako u -classpath se více adresářů odděluje ; (středníkem).

-verbose

tento parametr zobrazuje na výstup detaily o průběhu generování dokumentace např. parsing, loading aj. Bez tohoto parametru se vypisuje pouze jeden řádek pro každý zdrojový soubor.

-locale jazyk

označení jazyka, který používá JavaDoc. Vybráním jazyka ovlivňujete zdrojový soubor, který používá JavaDoc pro názvy popisků, nadpisů či navigaci. Více informací o tom co může být umístěno v tomto parametru je popsáno v java.util.Local. Uvedu jen pár základního hodnot en_US (Angličtina, Spojené státy Americké), en_US_WIN (Windows), pro češtinu cs_CZ a pro slovenštinu sk_SK. Ale nemusíte se bát, i když je čeština a slovenština v definici, tak v standardní instalaci není obsažena.

-encoding název

nastavení výstupního kódování souborů. JavaDoc podporuje kódování jako ASCII, Cp1252, ISO8859_1, UnicodeBig, UnicodeLittle, UTF8, UTF16, ale také ISO8859_2, Cp1250 či Cp852. Pokud by vám mohl poradit, píšete-li dokumentaci v češtině používejte kódování UTF či Unicode, ty mají budoucnost (i když s jejich podporou je to slabší), ostatní ne. Jediné co bych JavaDocu vytkl, je to, že do HTML automaticky neuvádí kódování daného souboru, což vcelku může znesnadnit výběr správného kódování. Tento problém lze vyřešit přes parametr -charset.

-Jflag

je o zobrazení hlášek přímo JavaDocu. Slova flag zde označuje nějaký parametr např. -version (zobrazí informace o verzi JavaDocu). Vcelku nemá smysl to používat pro jiný příkaz než version, nebo taky můžete skončit u desítek stránek, které stejně ani nebudete číst.

javadoc -J-version

-d adresář

určení do jakého adresáře se mají zapisovat vygenerované HTML soubory. Bez určení se automaticky používá aktuální adresář.

rem relativní odkaz javadoc -d docs *.java rem absolutní odkaz javadoc -d C:\Projekty\BookLet\Docs *.java

-use

přidá do záhlaví a zápatí (navigaci) odkaz „Use“. V tomto odkazu je pak specifikováno, které balíky a třídy používají daný balík. Dobře si můžete prohlédnout, jak to vypadá např. u balíku java.awt.color.

-version

přidá tag @version do generovaných dokumentů. Parametr je defaultně vynecháván.
Pokud zobrazit verzi JavaDocu, musíte použít i parametr -J.

rem zobrazení verze JavaDocu javadoc -J-version rem přidání verze do dokumentace javadoc -version *.java

-author

přidá tag @author do generovaných dokumentů.

-docfilessubdirs

povolení deep-kopírování adresářů s dokumentací. Označené podadresáře jsou pak rekurzivně zkopírovány do vytvářené dokumentace. Opakem je parametr -excludedocfilessubdir.

-splitindex

rozdělí index do více souborů, podle abecedy, každé písmeno jeden soubor.

-title název

parametr již neexistuje. Byl pouze ve verzi 1.2. Je nahrazen parametry -windowtitle či -doctitle.

-windowtitle název

název se zkopíruje do tagu názvu generovaných HTML souborů. Vzhledem k tomu, že se vlastně jedná o text do HTML tagu, tak nemůže obsahovat žádné další tagy. Nemáte-li definovaný tento parametr, JavaDoc pak používá parametr -doctitle.

rem text je lepší, kvůli mezerám uzavírat do uvozovek javadoc -windowtitle "BookLet for Java 2" *.java

-doctitle název

určuje titulek, který je umístěn nahoře v celkovém souhrnu (soubor summary-overview.html). Nemá vliv pokud se tento soubor negeneruje. Text je centrovaný a umístěn jako nadpis číslo jedna přímo pod navigací. Může obsahovat HTML tagy.

javadoc -doctitle "Java<sup><font size=\"-2\">TM</font></sup>" *.java

-header záhlaví

do parametru vložte text, který chcete umístit do záhlaví každé stránky - pravý frame. Text je umístěn vpravo od navigace. Tento parametr samozřejmě již může obsahovat HTML tagy.

javadoc -header "<b>BookLet</b> for Java 2<br>version 1.2" *.java

-footer zápatí

parametr má obsahovat text, který se umístí do zápatí generovaných stránek - pravých framů. Text je umístěn vpravo od navigace. Opět může obsahovat HTML tagy.

javadoc -footer "<b>BookLet</b> for Java 2<br>version 1.2" *.java

-bottom text

označuje text umístěný dole na každé generované stránce. Text je až pod navigací. Opět může obsahovat HTML tagy.

javadoc -bottom "Copyright © Švec Petr 2001<br>All rights reserved." *.java

-link docURL

vytvoření odkazu na již existující tzn. externí dokumentaci. Do docURL vložíte absolutní či relativní URL na místo, kde jsou dané dokumenty.

rem takto by např. šel nastavit odkaz na dokumentaci na Sunu javadoc -link http://java.sun.com/j2se/1.4/docs *.java

Poznámka: vzhledem k tomu, že to programují v Americe, tak pro vygenerování dokumentace musí být URL dostupná z vašeho PC.

-linkoffline docURL packagelistURL

tento parametr je obdobou pro -link. Jediný rozdíl je v tom, že externí dokumentace neobsahuje soubor package-list, ale měl by existovat soubor packageListDoc, který je lokální. Což umožňuje vytvořit dokumentaci bez připojení k Internetu. Do docURL vložíte odkaz asi na web, a do druhého parametru odkaz na místo na disku, kde máte dokumentaci.

javadoc -linkoffline "http://java.sun.com/products/jdk/1.4/docs/api" "C:\jdk1.4\docs\api\" nějaký_balík

-excludedocfilessubdir jméno:jméno:...

vyloučí označené podadresáře s dokumentací z SCCS (source-code-control subdirectories) kopírování. De facto je to opačná fce k -docfilessubdirs.

-group název_skupiny člen:člen:...

pomocí tohoto parametru lze rozčlenit jednotlivé balíky do skupin (v souboru overview.html). Jednotlivé členy patřící do skupiny jsou oddělování dvojtečkou. Chcete-li vytvořit více skupin použijte další parametr -group.

Poznámka: používáte-li hvězdičky je nutné uzavírat členy do uvozovek např. "java.util.*:javax.*"

-nocomment

zakázáni vložení veškerých komentářů či tagů do dokumentace. Vygeneruje se jen čistá kostra - žádné doprovodné texty. Podporuje verze 1.4.

-nodeprecated

zakázání vytvoření souboru s deprecated API, platí pro celou dokumentaci.

-noqualifier jméno:jméno:...

jména označují zakázané balíky, které nebudou zahrnuty. Jednotlivé jména se oddělují dvojtečkou.

rem zakázání všech javadoc -noqualifier all *.java rem zakázání specifických javadoc -noqualifier "java.util:java.util.*" *.java

-nosince

ignoruje tagy @since, nejsou pak uvedeny v dokumentaci.

-nodeprecatedlist

zakázání vytvoření soubor seznamu deprecated API (deprecated-list.html) a samozřejmě také vytvoření odkazu v navigaci.

-notree

zakázání vytvoření hierarchie tříd / interface v generovaných dokumentech. Defaultně je JavaDocem generována.

-noindex

zakázání vytvoření indexu generovaných dokumentů. Defaultně je JavaDocem generován.

-nohelp

zakázání vytvoření odkazu na Help v navigaci.

-nonavbar

zamezení vytvoření navigace, taktéž záhlaví a zápatí. Ale nevztahuje se na parametr -bottom.

javadoc -nonavbar -bottom "Copyright © ... 2001<br>All rights reserved." *.java

-quiet

potlačení výstupu na display při generování dokumentů.

-serialwarn

zobrazuje varování ohledně neexistující @serial tagů. Funguje ve verzi 1.3 a výše.

-tag jméno:umístění:hlavička

specifikace vlastního tagu. Tímto způsobem si např. můžete rozšířit JavaDoc o tag @copyright. Umístění znamená, kde se daná tag může vyskytovat: a (všude); p (balíky), t (typy tříd a interface), c (konstruktory), m (metody), f (pole).

// soubor.java ... /** ...  @copyright Švec Petr 2001  */ // příkazová řádka -javadoc -tag copyright:a:"Copyright" *.java

-taglet jméno

přesné jméno tagletu, která chcete přidat.

-tagletpath cesta

určení cesty k tagletům.

-charset název

označení výchozí znakové stránky HTML souborů. Specifikujete-li charset, nezapomeňte také specifikovat kódování viz. parametr -encoding

javadoc -charset "UTF-8" -encoding UTF8 myProg.java

Výsledek bude takový, že hlavička vygenerovaných dokumentů bude obsahovat řádek

<META http-equiv="Content-Type" content="text/html; charset=UTF-8">

-helpfile cesta\soubor

změna odkazu Helpu v navigaci na vámi zadaný soubor.

-src

vytvoří HTML soubor se zdrojovým kódem, ve kterém jsou očíslované řádky. V nižších verzích než 1.4 se tento parametr označuje jako -linksource.

-stylesheetfile cesta\soubor

určení cesty a souboru, ve kterém máte uložený svůj vlastní CSS styl pro dokumentace. Není nutné používat, pokud tvoříte standardní dokumentaci - JavaDoc vygeneruje svůj defaultní.

-docencoding název

určení výchozího kódování pro vygenerované HTML soubory. Opět do HTML souborů není vložena informace o kódování, tu je nutno dodat parametrem -charset.

A to je vše. Alespoň doufám.

Pro zájemce, kterým tento výčet nestačí, ještě připomenu, že zcela určitě jistě více podrobnějších informací o JavaDocu naleznete na serveru Sunu.