Dokumentační komentáře v C# at Ááá

Zář

18

Dokumentační komentáře v C#

Podrobně je to na MSDN, tohle je takový můj stručný výtah.

Dokumentační blok

Docbloky se v C# dělají trochu odlišně od Javy nebo PHP. Skládají se z řádkových komentářů, které mají o lomítko víc a jednotlivé části se uzavírají do jakoby-XML značek:

/// <summary>
/// Stručný popis třídy Foo.
/// </summary>
public class Foo
{
    /// <summary>
    /// Popis metody Bar.
    /// </summary>
    /// <param name="abc">Popis parametru abc.</param>
    /// <returns>Metoda vrátí 123.</returns>
    public int Bar(string abc)
    {
        return 123;
    }
}

(Takhle to vypadá dost nepřehledně, protože zvýrazňovač syntaxe FSHL neumí C#, v IDE to vypadá o něco lépe.)

Je možné používat i /** */ zápis, ale není to obvyklé.

Doporučované značky

Značka	Popis
`<c>`	Kus kódu v textu.
`<code>`	Víceřádkový blok kódu.
`<example>`	Popis příkladu použití.
`<exception cref="...">`	Popis možné výjimky, například: `<exception cref="SampleException">Thrown when...</exception>`.
`<include filename="..." tagpath="..." name="..." id="..." />`	Podle mě zbytečná pitomina. Možnost místo dokumentačního komentáře uvést odkaz do jiného souboru…
`<list type="...">`	Seznam nebo tabulka. Docela neohrabaný zápis, to asi moc často využívat nebudu, viz MSDN.
`<para>`	Odstavec. Pokud je třeba `<remarks>` sekce moc dlouhá, může přijít vhod rozčlenit do odstavců.
`<param name="...">`	Popis parametru metody, viz příklad výše.
`<paramref name="..." />`	Odkaz na parametr. Například v popisu metody: /// <summary> /// Parametr <paramref name=„foo“/> znamená kdovíco. /// </summary>
`<permission cref="...">`	Tuším, že to souvisí s CAS, ale k tomu jsem se ještě blíže nedostal, takže tomu nerozumím…
`<remarks>`	Doplňující informace, ukecanější pokračování stručného `<summary>`.
`<returns>`	Popis návratové hodnoty. Viz příklad výše.
`<see cref="..." />`	Odkaz z textu na nějaký kód, například: `/// Tato metoda k něčemu používá <see cref="SampleSpace.SampleClass"/>`.
`<seealso cref="..." />`	Odkaz na kód, který v dokumentaci patří do sekce „See Also“.
`<summary>`	Stručný popis popisovaného prvku (třídy, metody apod.).
`<typeparam name="...">`	Popis typového parametru. Například u třídy `SampleClass<T,U>` jsou typové parametry `T` a `U`, ty lze tedy dokumentovat touto značkou.
`<typeparamref name="..." />`	Podobné jako `<paramref name="..."/>`, akorát tady se odkazujeme na typový parametr.
`<value>`	Popis hodnoty property.

Využití

Především tuhle dokumentaci využívá IntelliSense.

Krom toho je možné z toho vygenerovat API dokumentaci nástrojem Sandcastle, postup ale není úplně přímočarý, viz:

This entry was posted by LLook on 20:38, Zář 18th 2008 and filed in Nezařazené.

Komentáře můžete sledovat přes RSS 2.0 kanál.

Komentářů už je 2. :-) to “Dokumentační komentáře v C#”

koubel
Posted: Zář 23rd, 2008 at 8.00

To XML v komentářích je asi lehce zpracovatelné nějakým externím nástrojem, ale na ruční zápis je to hrůza. A ty tři lomítka taky nic moc, řekl bych, že javadoc like dokumentace je o dost úspornější

LLook
Posted: Zář 23rd, 2008 at 17.55

Author Comment

Pro vytahání informací přímo ze zdrojáků je nutné parsovat i C# kód, aby bylo jasné, k čemu který komentář patří. To umí sám překladač (csc.exe), jehož výsledkem je XML soubor, který může vypadat například takhle:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>MvcApplication1</name>
    </assembly>
    <members>
        <member name="F:MvcApplication1.Views.Shared.Site.MainContent">
            <summary>
            MainContent control.
            </summary>
            <remarks>
            Auto-generated field.
            To modify move field declaration from designer file to code-behind file.
            </remarks>
        </member>
        <member name="M:MvcApplication1.Controllers.HomeController.Index">
            <summary>
            The front page of the web.
            </summary>
            <returns>Standard view.</returns>
        </member>
    </members>
</doc>

Teprve tenhle soubor je lehce zpracovatelný. Pokud bys chtěl zpracovávat přímo zdrojové kódy C#, tak se obtížnost od javadoc zápisu příliš lišit nebude.

Důvod, proč se XML zápis používá v samotných komentářích je spíše snaha o obecnost. Tagy jako <summary> nebo <param> jsou pouze doporučené, ale můžeš používat úplně jakékoli well formed XML. Například:

/// <todo category="gui" priority="low">Improve this form.</todo>

Takhle se třeba team může domluvit na nějakých vlastních značkách a tyto následně nějak vytahovat (např. pomocí DOM, XPath, XSLT nebo Linq to XML…) a třeba je automaticky vkládat do nějakého groupware. Možností je spousta.

Ruční zápis mi osobně přijde docela pohodlný, hrůza by to byla bez IntelliSense…

SexyComments by BorkWeb

Ááá

Zář

18