V tomto článku se dočtete, jak lze v C# pomocí XML komentářů psát přímo do zdrojového kódu dokumentaci k třídám, jejich metodám a vlastnostem a dalším prvkům. Podíváme se na některé základní tagy pomocí kterých lze psát kvalitní dokumentaci. Na konec si přečtete o nástroji NDoc, pomocí kterého lze z takto napsaných komentářů dokumentaci ve stejném tvaru, v jakém je MSDN.
reklama
Co tento článek ukazuje
- Jak lze dokumentovat zdrojový kód pomocí XML komentářů
- Formát kompilátorem generovaného souboru s dokumentací
- Tvorba dokumentace pomocí nástroje NDoc
Obdobně jako v Jave (více informací např. viz [1]), lze i v C# pomocí speciálního typu komentářů psát přímo do zdrojového kódu dokumentaci k třídám, jejich metodám a vlastnostem a dalším prvkům. Podpora pro psaní těchto komentářů je zabudována do samotného Visual Studia, které generuje kostru dokumentace automaticky. Z těchto komentářů je následně při kompilaci vygenerován XML soubor, který lze například přiložit k dll knihovně (Visual Studio poté z tohoto souboru načítá data pro Intellisense). Dále lze z XML souboru s dokumentací vygenerovat jednoduché webové stránky (příkazem ve Visual Studiu) a nebo pomocí open source nástroje NDoc vytvořit dokumentaci ve stejném tvaru, v jakém je MSDN.
V následujícím textu si nejprve ukážeme, jak lze komentovat kód v C# a následně se podíváme i na nástroj NDoc. Použití XML dokumentace se pokusím ukázat na jednoduchém WinForms ovládacím prvku u kterého lze nastavovat několik vlastností a má pár jednoduchých metod, ke kterým je potřeba dopsat dokumentaci (ovládací prvek jsem zvolil proto, že u oládacich prvků, je pro jejich další použití dokumentace velmi důležitá).
XML komentáře
Jak je patrné již z názvu, dokumentace se v C# zapisuje pomocí XML a je oddělena pomocí tří lomítek (///). XML komentáře lze psát před jakýkoliv datový typ (třídu, výčtový datový typ, delegate a další) a nebo před field (např. metodu, vlastnost nebo hodnotu u výčtového typu). V následující části se podíváme na základní tagy, pomocí kterých lze vytvářet dokumentaci.
Nejpoužívanější XML tagy
Pokud napíšete ve VS.Net tři lomítka před třídu nebo před metodu, VS.Net automaticky doplní základní dokumentační XML tagy. Základní shrnutí se vkládá pomocí tagu summary (minimálně tento tag by neměl u žádné třídy a metod chybět). U metody lze dále pomocí tagu param dopsat popis k jednotlivým parametrům. Návratovou hodnotu lze popsat v tagu returns. Další užitečný tag je remarks, ve kterém je vhodné dopsat další informace a případně poslat nějaké záludnosti. Pokud se při tvorbě dokumentace příliš rozepíšete, můžete text (například v tagu summary) rozdělit do více odstavců pomocí tagu para, který tvoří odstavec.
/// <summary>
/// Ovladaci prvek, ktery vypisuje dany text. Pozadi muze
/// byt dvoubarevny prechod a na prvek lze kreslit hvezdicky.
/// </summary>
public class ColorLabel : Control
{
/// <summary>
/// Pridava hvezdicku na pozici urcenou parametrem
/// <paramref name="position" />
/// </summary>
/// <param name="position">Pozice hvezdicky v pixelech</param>
public void AddStar(Point position)
{
}
}
V předcházející ukázce je ještě použit tag paramref pomocí kterého lze vytvořit odkaz na parametr metody. Podobným tagem je i see, který umožňuje vytvořit odkaz na nějakou jinou třídu, metodu atd.. V připadě tagu see se odkaz zadává pomocí atributu cref, který je při kompilaci kontrolován, aby odkaz měl smys. Pokud v atributu cref zadáte odkaz na neexistující třídu nebo metodu zobrazí se následující chybové hlášení:
warning CS1574: XML comment on 'XmlDocDemo.ColorLabel' has cref
attribute 'Qwerty' that could not be found
Při tvorbě dokumentace je také potřeba (a je to pro snadné pochopení dokumentace téměř nepostradatelné) poskytnout čtenáři ukázkový kód, který vysvětluje jak s objekt používat. Ukázkový kód je nejlepší připojit v tagu example, který je přímo určen k popsání příkladů. Delší blok zdrojového kódu se dá vložit pomocí tagu code (obdoba v HTML je pre) a jednoslovné části kódu - například názvy metod a vlastností, lze zvýraznit pomocí tagu c (obdoba v HTML by byla code).
/// <summary>...</summary>
/// <example>
/// Pomoci metody <c>AddStar</c> lze vkladat hvezdicky.
/// Nasledujici kod ukazuje jak vlozit hvezdicku na nahodne misto.
/// <code>
/// Random rnd=new Random();
/// lbl.AddStar(new Point(rnd.Next(lbl.Width),rnd.Next(lbl.Height)));
/// </code>
/// </example>
public void AddStar(Point position)
{
...
}
Dalším velmi užitečný tagem je exception (opět s atributem cref, pomocí kterého lze popsat výjimky, ke kterým může dojít při volání a vysvětlit situace které způsobí vyhození výjimky. Použití tohoto tagu demonstruje následující přiklad:
/// <exception cref="ArgumentException">
/// Popis kdy dojde k vyhozeni vyjimky.
/// </exception>
public void AddStar(Point position)
{
...
}
Z dalších tagů bych ještě rád upozornil na tag list pomocí kterého lze do dokumentace vkládat seznamy (očíslované, nečíslované a nebo jako tabulku). Tento tag je velmi užitečný při popisu jednotlivých hodnot u výčtových datových typů. Více o tomto tagu (a dalších o kterých jsem se nezmiňoval) naleznete například v MSDN - viz [2].
Ukládání dokumentace do externího souboru
Pokud chcete vytvářet dokumentaci opravdu důkladně, dostanete se dost možná do situace, kdy se stane soubr přes všechnu dokumentaci naprosto nepřehledným. V této situaci vám pomůže tag include, pomocí kterého lze ukládat dokumentaci do externího souboru. Dokumentace se (jak jinak) načítá z XML souboru a element ze kterého se bude dokumentace načítat je určen pomocí XPath cesty. Není problém dokumentaci načítat z externího souboru pouze z části, takže například tag summary zůstane jako součást kódu, ale ukázkový kód se bude načítat z externího souboru.
/// <summary>Ovladaci prvek ...</summary>
/// <include file='doc.xml' path='/documentation/member[@name="ColorLabel"]'/>
public class ColorLabel : Control
{
...
}
A ještě druhá část ukázky - soubor, ze kterého se dokumentace načítá:
<?xml version="1.0" encoding="utf-8" ?>
<documentation>
<!-- Obsah nasledujiciho elementu se vlozi do dokumentace -->
<member name="ColorLabel">
<example>
Nasledujici kod ukazuje ...
</example>
</member>
</documentation>
XML soubor s dokumentací
Jak jsem již psal, z XML komentářů je při komilaci vytvořen soubor, který obsahuje celou dokumentaci. Pokud distribuujete například dll knihovnu a dodáte k ní i tento soubor, bude VS.Net automaticky schopné načítat dokumentaci a zobrazovat jí prostřednictvím Intelisense. Při výchozím nastavení se soubor s dokumentací negeneruje a proto je potřeba jeho generování nejprve povolit ve vlastnostech projektu (jak ukazuje následující obrázek). Při kompilaci pomocí příkazové řádky se jedná o parametr /doc.
Výsledný XML soubor obsahuje v kořenovém elementu (doc) jednak element assembly, ve kterém naleznete jméno assembly a poté element members, ve kterém je uložena samotná dokumentace. Jenotlivé části dokumentace naleznete uvnitř tagů member, které mají pomocí atributu name určeno k jaké části kódu patří. Pro příklad name="T:XmlDocDemo.ColorLabel" znamená, že dokumentace patří k typu (T - type) XmlDoc.ColorLabel (Další předpony jsou například M - method a F - field). Tento soubor s dokumentací je součástí ukázkové aplikace, kterou si můžete stáhnout a hlouběji prozkoumat.
Nástroj NDoc
Přímo z Visual Studia je možné vygenerovat velmi jednoduché webové stránky, které dokumentaci zobrazí v čitelnější formě. Takto generované stránky nejsou ale jako dokumentace příliš použitelné a pravděpodobně proto začal vznikat skvělý open source program NDoc [3]. Pomocí tohoto nástroje lze vytvářet dokumentaci mimo jiné ve tvaru, který velmi přesně odpovídá stylu MSDN (přáklad je vidět na následujícím obrázku). Generovaná dokumentace je dokonce propojena s MSDN, takže pokud třída dědí například od prvku Control, bude v dokumentaci funkční odkaz a popis všech zděděných vlastností.
Použití nástroje je velmi intuitivní a po instalaci lze vše udělat pomocí velmi přehledného uživatelského rozhraní, proto o jeho použití nebudu nic dalšího psát, na oficiální stránce projektu naleznete i seznam článků, které jsou o tomto nástroji na internetu k nalezení (viz [4]). Pokud máte projekt okomentován, tak jak jsem popisoval výše, nemělo by vám vygenerování profesionální dokumentace trvat déle než minutu.
Soubory na stažení a odkazy