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í, Horní rám, Důležitý soubor, Klíčová funkce, Klíčový parametr, Díl, Komponenta, Podobné parametry, Webová prezentace

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


Aktuální číslo časopisu Computer

Jak rychlé je nabíjení bez drátů?

Test 11 sluchátek pro hráče

Aplikace, které vám zachrání dovolenou

Kompletní přehled datových tarifů