Užitečné komponenty pro Delphi a C++ Builder, díl 63.

Dnes si představíme dalšího pomocníka při programování. Tentokrát to bude program pro vytvoření podrobné dokumentace k vašemu zdrojovému kódu.
DelphiDoc

V tomto seriálu jsme si již představili různé pomocníky pro práci se zdrojovým kódem. Ukázali jsme si program pro formátování zdrojového kódu, pro jeho tisk i pro tvorbu přehledů o použitých knihovnách a zdrojích. Dneska si povíme o programu, který dokáže vytvořit ze zdrojového kódu poměrně podrobnou "technickou" dokumentaci.

Nejprve bych se rád zmínil o tom, pro koho je tento software vhodný, protože rozhodně nebude pro všechny. Programujete-li malý projekt pro vlastní potřebu, zřejmě nebudete nic podobného potřebovat. Pracujete-li však na něčem větším a navíc ještě v několika lidech, takže po sobě vzájemně musíte občas číst či opravovat zdrojové kódy, mohl by se vám tento program hodit. Nestačí totiž psát přehledně samotný zdrojový kód nebo ho do přehledné podoby upravit některým vhodným programem o kterém byla řeč, ale pochopitelně je důležité též opatřit náš "zdroják" komentáři.

Je to fráze, která se dokola opakuje snad vždy, když se někdo učí programovat. Komentovat, komentovat a zase komentovat. Ruku na srdce, kdo to dělá rád? Nikdo. Přesto je to právě při práci na větších projektech důležité, neboť velmi rychle můžete ztratit přehled o tom, co která procedura a funkce dělá, k čemu slouží jaký parametr a podobně.

Jste-li zvyklí komentáře psát, může se vám náš dnešní program od švédské společnosti SoftConsult hodit. Dokáže totiž právě na základě komentářů, vložených do zdrojového kódu, vytvořit poměrně dobře vypadající dokumentaci v podobě webových stránek. Má to pochopitelně několik podstatných podmínek. Jednak lze tento program použít samozřejmě pouze na okomentované zdrojové kódy, takže z vašich neokomentovaných kousků vám žádnou dokumentaci nevytvoří. Tedy, přesněji řečeno, dokumentaci vám vytvoří, ale ta bude tak chudá, že se z ní dají vyčíst maximálně vzájemné vztahy mezi jednotlivými objekty v projektu. Další naprosto nutnou podmínkou je to, aby komentáře splňovali přesné parametry zápisu (viz. dále).

Jak tedy program funguje? Samotné okno aplikace je velmi jednoduché a snad ani nestojí za to, abych vám sem dával jeho obrázek. Nejprve určíte, ze kterých zdrojových kódů bude dokumentace vytvořena. Jisté omezení je v tom, že se všechny zdrojové kódy musí nacházet ve stejném adresáři, protože jinak není program schopen nakreslit strom vzájemných závislostí. Cizí komponenty použité ve vašem projektu tak z tohoto stromového přehledu vypadnou. To však není zase tak důležité a navíc je aplikace stále ve vývoji, takže v některé z příštích verzí se můžeme dočkat vylepšení. Rovněž je nepříjemné, že nestačí vybrat jen projektový soubor, ale musíte ručně vybrat všechny soubory se zdrojovými kódy, které do projektu patří. Používáte-li program často pro stejný projekt, můžete si seznam souborů uložit a příště je již nemusíte jednotlivě do programu načítat, ale pouze načtete tento soubor se seznamem. V dalším kroku již jen vyberete adresář, do kterého má být webová dokumentaci uložena. Můžete rovněž specifikovat vlastní HTML soubor, který si sami vytvoříte a který bude obsahovat delší textový popis vašeho projektu. Tento soubor se pak stane součástí celé dokumentace. Obdobným způsobem si můžete sami upravit hlavičku webové prezentace. Stránky jsou totiž vytvořeny v podobě rámců, kdy horní rámec (ona zmiňovaná hlavička) obsahuje odkazy na jednotlivé sekce dokumentace jako jsou seznamy jednotek, tříd, funkcí atd.. Poté již jen stisknete tlačítko "Run" a webová prezentace je vytvořena.

Tolik tedy k používání samotného programu, který je opravdu velmi jednoduchý. Teď se ale musíme zmínit o formátu, ve kterém musí být komentáře ve zdrojových kódech napsány. Jedná se o systém "tagů" či, chcete-li, klíčových slov, která jsou vždy uvozena znakem zavináče a za nimi následuje samotný text vašeho komentáře. Tato klíčová slova jsou naštěstí jen čtyři, takže nehrozí, že si je nezapamatujete. Na druhou stranu vám nemusí svým rozsahem stačit, ale to je věc názoru a dalších verzí programu. Klíčová slova popisují parametry dané funkce, dále návratové hodnoty, parametr deprecated pro nedoporučované funkce a posledním je odkaz na další příbuzná témata. Nejlepší bude asi příklad, takže s dovolením použiji ten, který naleznete na stránkách produktu. Ze zdrojového kódu, zapsaného v této podobě:

{** @deprecated "Now replaced by OpenTables2"
    Open all tables that is marked for opening

    @param  fastOpen    Use the fast opening routine
    @return            Returns true if Ok
    @see                OpenTables2}
function TfrmParentForm.OpenTables(fastOpen: boolean): boolean;
begin
  ......
  ......
end;

bude aplikací vytvořen popis, který vypadá takto:

function OpenTables(fastOpen: boolean); virtual;

Deprecated "Now replaced by OpenTables2"
Open all tables that is marked for opening
Parameters
fastOpen :Use the fast opening routine
Returns
Returns true if Ok
See Also
OpenTables2

Myslím, že z tohoto příkladu je již zřejmé, jak celý proces funguje. Takto jsou přečteny všechny komentáře vašich zdrojových kódů, ke všem funkcím jsou vytvořeny podobné popisy, jsou vytvořeny vzájemné vazby a vše je uloženo jako webová prezentace. Sami si tedy utvořte obrázek o tom, jestli je tento pomocník pro vás vhodný či ne. Je jasné, že na již rozpracované projekty nebude program zřejmě příliš vhodný, ale pokud začínáte projekt nový, jste zvyklí psát komentáře a jste ochotni se podřídit nutnosti dodržet předepsaný formát komentářů, určitě byste měli o použití tohoto programu zauvažovat.

www
verze: 2.0
Delphi: ano
C++ Builder: ne

Váš názor Další článek: Přiznání k dani z přidané hodnoty můžete podat po internetu

Témata článku: Software, Programování, Klíčový parametr, Komponenta, Podobné parametry, Díl, Horní rám, Webová prezentace, Klíčová funkce, Důležitý soubor


Určitě si přečtěte

Alan Turing: Genius, který matematicky stvořil počítač

Alan Turing: Genius, který matematicky stvořil počítač

Řešením matematického problému se dostal k modelu teoretického stroje, který nese jeho jméno a je základem logiky univerzálních počítačů.

Pavel Tronner | 56

Nová zbraň Microsoftu proti iPadu: Levný tablet Surface Go bude stát jen deset tisíc

Nová zbraň Microsoftu proti iPadu: Levný tablet Surface Go bude stát jen deset tisíc

** Microsoft představil nový tablet Surface Go ** Nový model zaujme nízkou cenou, ale schopnostmi zařízení Surface ** Microsoft nepoužil čip ARM, ale klasický procesor od Intelu 

Karel Javůrek | 116

Porno insider: Jak virtuální realita vstupuje do filmů pro dospělé

Porno insider: Jak virtuální realita vstupuje do filmů pro dospělé

** Pornografie údajně představuje třetinu internetové obsahu a je technologický tahounem ** Do erotického obsahu postupně zasahuje i virtuální realita ** Kromě vizuálního vjemu se pracuje také na virtuálním uspokojení toho hmatového

Jan Dudek | 28

Budoucnost elektroniky: čeští vědci stojí za revolučním čipem, který nemá ve světě obdoby

Budoucnost elektroniky: čeští vědci stojí za revolučním čipem, který nemá ve světě obdoby

** Čeští vědci pod vedením Tomáše Jungwirtha vyvíjí nový typ revolučního paměťového čipu ** Zatímco v současnosti elektronika pracuje s elektrony, v budoucnu to budou spiny elektronů ** Čipy budou moci být klidně i 1 000x rychlejší a úspornější

Karel Javůrek | 32

Apple dal do MacBooku procesor Core i9 a 4TB SSD. Ani se neptejte, co za to chce...

Apple dal do MacBooku procesor Core i9 a 4TB SSD. Ani se neptejte, co za to chce...

** Apple aktualizoval notebooky MacBook Pro, dostaly nový hardware ** Těšit se můžete na nové procesory a větší paměť ** Cena nejvybavenějšího modelu překročí 200 tisíc korun

Martin Miksa | 99

Rekordy počasí: V Česku to ještě jde, skutečné extrémy zažívají jinde

Rekordy počasí: V Česku to ještě jde, skutečné extrémy zažívají jinde

** Teplotní extrémy dokážou překvapit. Seznamte se s rekordy v Česku i ve světě ** Rekordní hodnoty jsou mnohdy až k neuvěření ** Zjistěte, kdy ke bylo největší horko, zima, déšť či vítr

Karel Kilián | 7


Aktuální číslo časopisu Computer

Velký test 18 bezdrátových sluchátek

Vše o přechodu na DVB-T2

Procesory AMD opět porážejí Intel

7 NVMe M.2 SSD v přímém souboji