|
Nejlepším zdrojem je MSDN, kde je většina členů XML dokumentace řádně popsána: http://msdn.microsoft.com/en-us/library/... Důležité jsou zejmena Summary, Param, Returns, Remarks... Záleží, co zrovna popisujete. U Vaší funkce pro součte by mohla dokumentace vypadat třeba následovně:
''' <summary>
''' Sečte dvě hodnoty typu System.Double a vrátí výsledek.
''' </summary>
''' <param name="num1">První operand.</param>
''' <param name="num2">Druhý operand.</param>
''' <returns>Výsledek operace součtu.</returns>
''' <remarks>...</remarks>
Public Function Součet(num1 As Double, num2 As Double) As Double
Můžete si dát záležet více nebo méně na tom, jak přesně a věcně popíšete jednotlivé položky. V první řadě XML komentáře slouží k lepší orientaci v kódu Vám i další vývojářům, kteří k projektu přijdou a v druhé řadě se pomocí různých nástrojů dají z těchto komentářů automatizovaně vytvořit dokumentace. Pokud vyvíjíte knihovnu určenou pro třetí stranu, rozhodně není na škodu si dát na dokumentaci záležet, s dobře zdokumentovanými knihovnami se pracuje o poznání lépe a rychleji, než s nezdokumentovanými, nebo špatně zdokumentovanými knihovnami. Pokud ale vyvíjíte pro sebe, nebo pracujete na části projektu, která neposkytuje veřejné rozhraní, asi nemá moc smysl nějak pečlivě komentovat soukromé členy, pokud je samo o sobě zřejmé, co dělají. To ovšem neplatí při práci v týmu, kdy musí další vývojáři získat okamžitý přehled o tom, co nově implementované části kódu dělají v kontextu s již implementovanými částmi a celkovým účelem projektu. K tomu jsou dobré například <see>, <seealso>, <remarks> (u Vašeho příkladu jsem ho uvedl pouze pro ilustraci, ale běžně se používá pro poznámky a další informace, které by měl vědět vývojář při používání metody, a které nemusí být hned zřejmé), <example>, <code> a pdobně. Zdroje: http://msdn.microsoft.com/en-us/library/... http://msdn.microsoft.com/en-us/library/... http://msdn.microsoft.com/en-us/library/... http://msdn.microsoft.com/en-us/library/... Na MSDN najdete spoustu článků věnujících se nejen XML komentářům, ale také uvidíte, jak se které XML komentáře projeví na dokumentaci, viz třeba: http://msdn.microsoft.com/en-us/library/... kde vidíte logické celky parametry, návratová hodnota, výjimky, ...
|