Doc-O-Matic 1.1

Tvorba dokumentace je ve většině případů prašivá práce. Člověk prosedí hodiny nad přihlouplým textovým editorem a jedním prstem vyťukává nenáviděná slova s vědomím, že to stejně nikdo nebude číst.

Tak by mohl znít úvod. Ale podívejme se ještě na jeden. Vyspělý programátor se (údajně) pozná podle toho, jak kulturně (a kvalitně) píše nejen zdrojový kód, ale hlavním měřítkem je množství, vzhled, způsob, obsah, čitelnost a srozumitelnost komentářů, kterými své dílo prokládá. Zda-li je to pravda či nikoliv nechme stranou. Jak by řekl Jára Cimrman, můžeme o tom vést spory, můžeme i nesouhlasit, ale to je tak všechno, co se proti tomu dá dělat.

Kvalitních nástrojů na tvorbu programátorské dokumentace jsem moc neviděl, dokonce mohu říct, že jsem narazil na první. Nejprve je ale potřeba říci, co to taková programátorská (či programová) dokumentace je.

Naprosto běžným denním rituálem vývojáře je, že když napíše či opraví svůj nebo cizí kód, zapíše to do dokumentace a okomentuje to. Pokud se vyvíjí velký projekt, je zapotřebí popsat architekturu, rozhraní, systémové požadavky a další věci, které si může každý „splychtit“ v nějakém tom Wordu, případné grafy v některém kreslítku či obrázky v Malování. To ale ještě nepatří mezi to nejhorší.

„Pravá slast a nekonečné vlny rozkoše“ přicházejí s komentováním a popisem podprogramů, metod, jejich parametrů, vlastností objektů a další. Uživatel těchto funkcí však již tento popis potřebuje. A často velmi nutně. Pokud programujete pod Windows, přiznejte si, kolikrát se díváte do nápovědy k API funkcím či k metodám tříd. A o tomhle vlastně bude řeč.

Ať již jste zastánci programování v Delphi (mimochodem již je v prodeji šestá verze), C++ Builderu nebo Visual C++, existuje pro vás aplikace typu self-made. Tyto aplikace vznikají ve většině případů tehdy, když autor nenašel nic lepšího na to, co potřeboval ke své práci. A právě takový je Doc-O-Matic, produkt na tvorbu nápovědy k vaším zdrojovým textům ve výše uvedených programovacích jazycích.

Po prvním spuštění aplikace se sice můžeme podívat po prostředí, ale mnohem lepší je začít hned pracovat. Základem je tzv. projekt, ve kterém si definujete vše, co a jak bude zdokumentováno. K definování projektu slouží intuitivní průvodce, který v jedenácti krocích od vás získá relevantní údaje jako je název projektu, soubory, které chcete mít zdokumentovány, způsob komentování (k tomu se ještě dostaneme), co vše dokumentovat a další. Ač to na první pohled nemusí být jasné, vše, co zadáte, lze následně změnit.

Píšeme komentáře

Zastavme se nejprve u způsobu psaní komentářů. Doc-O-Matic podporuje dva druhy. Prvním je psaní všech komentářů k danému prvku před něj, druhý je za něj. To s sebou nese pár úskalí. Největší problém bude zvyknout si totiž na toto jasně definované pravidlo. Mě osobně to chvilku trvalo, protože jsem byl zvyklý psát komentáře k objektu před něj a následně komentovat metody a atributy za. To byl ale jediný problém (můj, nikoliv aplikace), se kterým jsem se setkal.

Ale určením umístění komentářů nic nekončí, naopak zábava se teprve rozjíždí. Při psaní komentářů můžete použít speciální „tagy“, kterým lze následný výstup dále formátovat. Uveďme například zákaz formátování, seznamy, určení zdrojového textu a další.

Pokud programujete v nástrojích firmy Borland, pak jistě velmi důvěrně znáte jejich nápovědu. Hierarchie dědičnosti, vlastnosti či metody ve zvláštním okně a standardní psaní textu nápovědy: krátké představení, přesnou deklaraci, význam parametrů, popis a případné další věci jako poznámka a podobně.

Ohromnou předností tohoto produktu je nejen to, že tohle umí také, ale skutečnost, že díky integraci nápovědy vytvořené v Doc-O-Maticu do prostředí Delphi či C++ Builderu můžete volat například standardní nápovědu VCL. To vše lze zajistit pomocí speciálního tagu.

Protože o psaní komentářů mohu básnit dál, umístil jsem na doprovodné CD zdrojový kód jednotky v Delphi a výslednou nápovědu, abyste mohli sami vidět, jak jednoduše lze docílit profesionálně vypadající nápovědy například k vašim komponentám.

Seznámení s prostředím

Ale pojďme konečně k prostředí produktu. To je rozděleno na dvě části. Tou první je panel s pohledy nalevo, druhou pak – zabírající největší plochu – zbývající část, která je kontextově závislá na vybraném pohledu.

Pohled Info obsahuje pouze základní informace a odkazy na další pohledy případně příkazy, které lze najít v nabídce aplikace. Zato pohled Symbols již obsahuje dostatečně zajímavé informace. Ve stromové struktuře jsou zobrazeny všechny třídy, typy, konstanty a další prvky zdrojových kódů, které jste do projektu vložili. U každého prvku máte k dispozici zdrojový text deklarace, informace o tom, zda je již zdokumentován či nikoliv a pokud je, pak vidíte výsledek daného tématu jako v nápovědě (viz obrázek). Tento strom lze vidět jednak jako seznam všech tříd, všech typů a podobně, nebo jej seskupit podle souborů, ve kterém se daný prvek nachází.

Když se tak procházíte po jednotlivých prvcích a koukáte, co již je a co dosud není okomentováno, řeknete si, tohle je dost nepřehledné, chtělo by to něco, no, něco… Ano, je to třetí pohled pojmenovaný QA View. Ten pomocí barevných čtverečků zobrazuje přesně to, co potřebujeme. Navíc jsou tyto čtverečky seskupovány například tak, jak metody náleží objektu. Po najetí myši nad čtvereček přesně vidíme, co je již hotové, a co je potřeba ještě okomentovat a opět, podobně jako v pohledu předchozím, se zobrazuje výsledek tak, jak bude vidět v nápovědě.

Pokud zjistíte, že jste v projektu některé zdrojové soubory chybí nebo naopak přebývají, pak můžete v pohledu Source Files provádět potřebné změny.

Jestliže máte potřebu do nápovědy kromě toho, co je ve zdrojových textech, přidat další věci, můžete to udělat pomocí pohledu Topic Files. Díky tomu lze k výsledu připojit další informace, které je potřeba mít v projektu zahrnuty.

Nejkomplexnějším pohledem je Configuration, který obsahuje velké množství nastavení, jak má výsledná nápověda vypadat, jak se má chovat ke zdrojovým textům a další. Projděme si to nejzajímavější.

U způsobu psaní komentářů jsem zmínil, že díky speciálním slovům lze text formátovat tak, aby výsledek vypadal podobně, jak je to například v nápovědě k Delphi. Právě zde lze zvolit, která slova to mají být. Máte definované sekce (například parametry, návratová hodnota, viz také a další) a ke každé sekci si můžete sami určit, která slova (množné číslo je správně) patří do této sekce.

Můžete změnit to, kde má Doc-O-Matic hledat komentáře (zda před či za prvkem), můžete komentovat ve stylu JavaDoc, u různých jazyků lze nastavit způsob zpracování zdrojových textů a další.

Příjemnou vlastností je také vynutit si u každého prvku komentář, případně si určit standardní text, který u prvku bude zobrazen, nebyl-li dosud okomentován. U tříd lze například nechat dokumentovat pouze privátní atributy a veřejné metody, nebo naopak a nebo úplně jinak. Jak je libo.

Posledním pohledem je Messages, kde jsou veškeré zprávy, které se vygenerují společně s výslednou nápovědou a kromě jiného mohou obsahovat seznam dosud neokomentovaných prvků.

Ostatní

Ačkoliv mateřskou zemí produktu je Rakousko, mluví na vás anglicky, což je samozřejmé. Méně samozřejmé je to, že výsledná nápověda, ať již klasický WinHelp či HTMLHelp, může obsahovat vše česky. K dispozici jsou slovníky všech pojmů, které se používají při generování. Standardně mezi nimi sice čeština není, ale jedná se o textový soubor, kde přeložit pár slovíček je otázkou max. dvaceti minut (vyzkoušeno). Stejně tak je potřeba v případě použití češtiny v komentářích nastavit způsob kódováni. Ale to se děje při definici projektu a není to nic, co by nezvládl běžně vycvičený uživatel, natož programátor.

Doc-O-Matic je první produkt, kde jsem ve standardním uživatelském prostředí viděl všude vysvětlující texty. Abych to upřesnil — v běžném prostředí je například u vstupních prvků pár slovy řečeno, co se očekává (například Zadejte rodné číslo). Zde, kromě téhož, je bližší vysvětlení, co to znamená, takže případný zmatkař nemusí hned mačkat klávesu F1. Ale pokud mu přesto tento popis nestačí, je k dispozici kvalitní nápověda, kde se dozví vše, co potřebuje.

Je jasné, že se zdrojové texty mění a s tím i komentáře, ze kterých se nápověda generuje. K znovunačtení slouží pohotové tlačítko v paletě nástrojů. Stejně jednoduché je i vygenerování nápovědy (HLP i CHM). Co více si přát?

Tak si to zrekapitulujeme

Jak jsem napsal na konci úvodu, aplikace byla napsaná z toho důvodu, že autoři nenašli nic lepšího. Pokud bych měl k hodnocení stejný přístup, rozhodně bych nic nového nepsal, protože to, co se mi líbí, co se nechá používat a funguje dobře, jsem již našel. Jestliže jste kdy chtěli mít programovou nápovědu integrovanou do vývojového prostředí, těžko naleznete něco lepšího.

S produktem jsem jako vývojář navýsost spokojen a mohu jedině doporučit. Pokud jsem komunikoval s výrobcem, vše bylo bez problémů vyřešeno během pár minut (díky stejné časové zóně a ochotě druhé strany). Snad jedinou nevýhodou se může zdát cena, která je dost vysoká, ale pevně věřím, že se investice velmi rychle vrátí.

Plusy, mínusy, závěr

Plusy

• Myšlenka
• Velmi mnoho možností konfigurace výstupu
• WinHelp i HTMLHelp
• Propojení s jinými nápovědami (API, VCL, …)

Mínusy

• Cena
• Někteří si budou muset zvyknout psát komentáře jiným stylem.

Závěr

• Plně vyvinutý systém pro tvorbu nápovědy ze zdrojových textů Delphi či C++. Nepostradatelný pomocník pro dodavatele knihoven kódů.
• Cena: 1–2 uživatelé USD 349
• Výrobce: toolsfactory GmbH, http://www.toolsfactory.com
• Kontakt: http://www.doc-o-matic.com