Dokumentacja

Komentarze możemy wstawiać pomiędzy znaki /* ... */ . Dozwolone jest także użycie //... pozwalającego na wstawienie komentarza do końca bieżącego wiersza.

Ponadto w C# możemy wstawiać w kodzie źródłowym komentarze dokumentacji. Dzięki nim automatycznie, podczas kompilacji, zostanie wygenerowana dokumentacja. Komentarze dokumentacji wstawiamy używając /// ... (pozwala to wstawić komentarz do końca bieżącego wiersza). Służą one opisaniu typów oraz składowych.

Kompilator sprawdza spójność komentarzy dokumentacji i tworzy z nich plik dokumentacji w XML (w tym celu musimy podczas wywoływania kompilacji przekazać do kompilatora parametr /doc:<nazwaPliku>).

Przykład kodu źródłowego:

// Plik Program.cs
class MojaKlasa {
   /// <summary>
   /// Metoda wywoływana z
   /// <see cref="Main"> Main </see>
   /// </summary>
   /// <param name="a"> a to… </param>
   void funkcja( int a ){
      ...
   }
   ...
}

<?xml version="1.0"?>
<doc>
   <assembly>
      <name> Program </name>
   </assembly>
   <members>
      <member name="M:MojaKlasa.funkcja( System.int )">
         <summary>
           Metoda wywoływana z
           <see cref="M:MojaKlasa.Main"> Main </see>
         </summary>
         <param name="a"> a to... </param>
      </member>
   </member>
    ...
</doc>

Pewne znaczniki XML ( <?xml ...>, <doc>, <members>, <member>, <assembly>, <name> ) są automatycznie generowane przez kompilator (tworzą podstawowy szkielet dokumentacji). Użytkownik może tworzyć własne znaczniki - przenoszone do dokumentacji w sposób dosłowny - lub używać znaczników predefiniowanych.

Jeśli wewnątrz znacznika pojawia się parametr cref (niezależnie czy jest to znacznik predefiniowany czy użytkownika), to jego wartość jest rozwijana (zostaje podana pełna nazwa oraz przedrostek opisujący typ odwołania, gdzie M oznacza odwołanie do metody, T do typu, N do namespace, ... ).

<summary> : wewnątrz tego znacznika krótko opisujemy typ lub jego składową

<remarks> : wewnątrz tego znacznika dokładnie opisujemy typ lub składową

<param> : służy opisaniu parametru metody. Zawiera obowiązkowy parametr name. Jeśli stosujemy znacznik param w stosunku do któregokolwiek z parametrów metody, to musimy także opisać wszystkie inne jej parametry, np. <param name="nazwa"> opis parametru </param>

<returns> : Opisuje wartość zwracaną przez metodę, np. <returns> ... </returns>

<example> : Pozwala podać przykłady kodu w dokumentacji. Znacznik ten z reguły zawiera pewien opis oraz zagnieżdżone znaczniki <c> oraz <code>.

<c> : służy podaniu w dokumentacji przykładowego kodu. Może być umieszczony wewnątrz znacznika <example>, ale nie musi.

<code> : służy podaniu przykładowego kodu. Znacznika <code> powinno się używać zamiast <c> w przypadku, gdy fragment kodu ma więcej niż jedną linijkę.

<see> : wstawia do dokumentacji odnośnik do miejsca opisującego inny typ lub składową. Posiada parametr cref, który służy podaniu nazwy typu/składowej. Np. <see cref="MojTyp"> MojTyp </see>

<seealso> : to samo co <see>. Najczęściej jednak <see> jest formatowane jako odnośnik w opisie, natomiast <seealso> tworzy osobną sekcję 'zobacz też'.

<value> : służy opisaniu właściwości należącej do klasy, np. <value> jest to... </value>

<para> : oznacza paragraf. Nie ma żadnego znaczenia logicznego, pozwala tylko ładniej sformatować tekst. Jest używany wewnątrz takich znaczników jak <remarks> czy <returns>

<list> : wstawić listę. Nie ma żadnego znaczenia logicznego, pozwala tylko ładniej sformatować tekst. Wewnątrz znacznika listy możemy użyć dodatkowych znaczników <item> oraz <listheader>. Ponadto określamy parametr type listy ("bullet", "table", "number"). Np. <list type="number"> <item> Struktura </item> … </list>

<exception> : pozwala opisać wyjątek zgłaszany przez metodę. Opcjonalny parametr cref służy podaniu typu wyjątku. Np. <exception cref="MojeWyjatki"> opis bledu </exception>

<paramref/> : Pozwala na wstawienie odnośnika do opisu parametru. Posiada parametr name identyfikujący parametr. Np. ... Parametr <paramref name="Str1" /> jest ważny, gdyż ...

<permission> : opisuje uprawnienia wymagane do dostępu do składowej lub typu. Opcjonalny parametr cref służy podaniu typu reprezentującego uprawnienia.