Generování dokumentace pro C#

Většina programátorů se snaží dělat jedinou práci - programovat. Neuvědomují si však, že vlastní programování zabere pouze nepatrnou část jejich života. Dalším důležitým (nikoliv však jediným) aspektem je psaní dokumentace.

O psaní dokumentace se vedou sáhodlouhé (a téměř zbytečné) diskuse. Má se nejprve programovat a pak psát dokumentace? Má dokumentaci psát programátor nebo někdo jiný? Čassto si také programátoři říkají: „Teď mi jde programování, tak to zdokumentuji až potom“. Že se k tomu nakonec nedostanou, je téměř jisté. Ten zbytek pak dokumentaci až na výjimky odflákne. To má za následek mnohem větší časový požadavek na pochopení kódu, ke kterému se kdokoliv, včetně autora (!), po čase musí vrátit. Je tedy jasné, že dokumentovat se musí co nejdříve.

K ulehčení tu jsou však speciální nástroje, které se snaží programátorům pomoci (pro Delphisty např. skvělý Doc-O-Matic, recenze zde). Často je k tomu potřeba udělat jediné: vhodně komentovat zdrojové kódy (jako např. v Javě pro JavaDoc). Dnešním úkolem je podívat se na způsob psaní komentářů v C# a následně na tvorbu dokumentace.

Než bychom nadále chodili kolem horké kaše, vrhneme se na konkrétní přiklad. Našim úkolem bude vytvořit a zdokumentovat jednoduchou třídu MathOperation, která bude implementovat základní matematické operace (násobení a dělení). Na obrázku je uveden zdrojový kód, u něhož jsou pochopitelně nejdůležité komentáře. Pokud je potřeba zajistit, aby komentář měl zvláštní význam, místo dvou lomítek je nutné napsat tři. Uvnitř komentářů se pak do definovaných XML elementů zapisují relevantní informace. Projděme si tedy celý postup od začátku.

Nejprve napíšeme definici třídy, zatím bez metody. Nyní umístěte kursor na řádek před třídu a začněte psát komentář, tedy tři lomítka. Jestliže používáte Microsoft Visual Studio .NET, máte práci velmi ušetřenou. VS.NET totiž pochopí, co chcete dělat, automaticky doplní zbývající řádky včetně XML elementu summary a umístí kursor na prázdný řádek mezi počáteční a koncový element. Při přechodu na nový řádek se automaticky doplní nová tři lomítka. Taktéž zde funguje IntelliSense, který nabízí ty správné elementy. Popište si tedy třídu a poté zapište deklaraci metody. Opět podobně umístěte kursor nad deklaraci a zapište tři lomítka. VS.NET nyní vygeneruje XML elementy nejen pro souhrn, ale i pro jednotlivé parametry a výstupní hodnotu. Stačí tedy pouze napsat, k čemu metoda a její parametry slouží.

Dobře, máme okomentovanou třídu a metodu, ale dokumentaci ještě generovat nebudeme. Naopak zkusíme třídu použít. Cvičně si vytvořte formulář, na něj vložte tlačítko, v obsluze kliknutí vyvolejte IntelliSense a začněte psát název třídy MathOperation. Až se v seznamu kursor zastaví na naší třídě, zobrazí se bublinková nápověda s textem, který jsme vložili do elementu summary. Naprosto stejně se to chová při vkládání metody. Pokud zadáváte parametry, získáte informace o každém z nich. A to jsme zatím nic nepřekládali, nic negenerovali, pouze jsem zapsali pár komentářů!

   

Už nyní jsme dosáhli velmi slušné funkčnosti, díky které je psaní zdrojového kódu mnohem příjemnější. Současně s tím dozrál čas na generování dokumentace. Je snad něco jednoduššího než říct, že k tomu slouží parametr docs, který se předá překladači? Pro změnu nyní zapomeneme na Visual Studio a spustíme řádkový překladač. Pokud se zdrojový soubor jmenuje MyFile.cs, pak syntaxe vypadá následovně:

csc MyFile.cs /docs:MyFile.xml

Výsledkem bude kromě assembly XML soubor, který již můžete pomocí XSLT stylů převést do čehokoliv jiného. Už ovšem slyším vaše připomínky: „Kdo se má plácat s nějakým XSLT stylem?“ Nemějte strach. Pokud nemáte čas či náladu, využijte možností Visual Studia a menu Tools zvolte položku Build Comment Web Pages… Zobrazí se dialog, ve kterém vyberte projekt či řešení a zbytek již udělá VS za vás (výsledek můžete vidět na doprovodném CD).

Zdálo by se, že jsme u konce, ale není to pravda. Až dosud jsme v komentářích používali tři XML elementy, což je na dokumentaci žalostně málo. Co když chci udělat odkaz např. z jedné metody na druhou? Nebo chci vložit příklad? To ovšem není problém. K dispozici je totiž dalších třináct elementů (přehled všech naleznete v následující tabulce).

Název tagu	Popis
c	Text v tomto tagu indikuje zdrojový kód.
code	Podobný jako tag c, ale určuje víceřádkový kód.
example	Popis příkladu.
exception	Odkaz na výjimku.
include	Díky tomuto tagu lze mít dokumentaci v externím souboru.
list	Umožňuje vytvořit seznam.
para	Vkládá text do odstavce.
param	Popis parametru.
paramdef	Odkaz na parametr.
permission	Popis přístupnosti metody.
remarks	Podrobnější popis třídy/metody.
returns	Popis návratové hodnoty.
see	Odkaz na jiný element.
seealso	Specifikuje text, který bude zobrazen v sekci See also.
summary	Krátký popis třídy/metody.
value	Popis vlastnosti třídy.

Jakmile začnete používat všechny uvedené elementy, zjistíte, že při generování dokumentace Visual Studio některé z nich ignoruje (např. example). To je ovšem velmi nepříjemné. Naštěstí si to několik vývojářů včas uvědomilo a vznikl Open source projekt NDoc (viz odkazy v rámečku), který tvoří dokumentaci mnohem pokročileji než Visual Studio. Aplikaci NDOc je potřeba „předhodit“ řešení z Visual Studia a/nebo assembly společně s odpovídajícím XML dokumentem vygenerovaným pomocí přepínače docs překladače csc.exe. Pak nastavíte několik parametrů, jak má vypadat výsledek, a je možné začít generovat a následně prohlížet. Ukázku opět uvidíte na doprovodném CD.

Jak bez Visual Studia

1. Můžete použít libovolný editor pro psaní zdrojových kódů. Lze použít i NotePad, ale existují již i takové, které umí zvýraznit syntaxi a volat externí překladače (např. rkEdit).
2. Vytvořte si nějakou třídu a metody, okomentujte je.
3. Nyní můžete spustit překlad společně s generováním dokumentace v XML (je jasné, že je potřeba mít nainstalovaný MS .NET Framework Software Development Kit, odkaz viz níže), např.: „c:\WINNT\Micro­soft.NET\Frame­work\v1.0.3705\csc­.exe“ mymath.cs /doc:mymath.xml
4. Spusťte NDoc, pomocí tlačítka Add zadejte assembly (mymath.exe), automaticky se doplní cesta ke XML dokumentaci.
5. Proveďte Build
6. Je hotovo, dokumentace se může prohlížet.

Závěr

Co k tomu říct závěrem? Dokumentace zdrojových kódů v C# lze vytvářet velmi jednoduše, navíc pokud používáte Visual Studio .NET, pak psaní speciálních komentářů funguje naprosto automaticky včetně IntelliSense. Co více si přát? Na doprovodném CD jsem umístil ukázkový soubor v C#, vygenerovanou dokumentaci z Visual Studia i NDocu a nakonec stručný popis, jak bez Visual Studia generovat dokumentaci (zde o kapitolu výše).

Související odkazy

• NDoc
• MS .NET Framework Software Development Kit
• MS .NET Framework Redistributable