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


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

Solární panely v silnici vypadaly jako dobrý nápad. V praxi se ale neosvědčily

Solární panely v silnici vypadaly jako dobrý nápad. V praxi se ale neosvědčily

** Nápad použít na silnice místo asfaltu solární panely vypadal slibně ** Praktické testy však odhalily celou řadu nevýhod ** Nejhorší je směšná účinnost ve srovnání s fotovoltaickou elektrárnou

Karel Kilián | 65

Musk pošle lidi na oblet Měsíce. Japonský podnikatel Maezawa vezme na cestu až osm umělců

Musk pošle lidi na oblet Měsíce. Japonský podnikatel Maezawa vezme na cestu až osm umělců

** SpaceX chce nejdříve v roce 2023 vyslat lidi na oblet Měsíce ** Hlavním pasažérem bude japonský podnikatel Jusaku Maezawa, který vezme na cestu až 8 umělců ** Pětidenní cesta proběhne v chystané lodi BFS

Petr Kubala | 14

Kde se bere elektřina v zásuvce? Poznejte 10 tajemství venkovních stožárů s dráty

Kde se bere elektřina v zásuvce? Poznejte 10 tajemství venkovních stožárů s dráty

Elektřina se vyrábí v elektrárnách, ale do zásuvek v našich domovech to pak má ještě hodně daleko. Dnes se na tuhle dlouhou cestu podíváme.

David Polesný | 82


Aktuální číslo časopisu Computer

Jak vytvořit a spravovat vlastní web

Velký test herních klávesnic a DVB-T2 tunerů

Vše o formátu RAW

Vybíráme nejlepší základní desku