How this...W poprzednimwpisie opisałem jak łatwo dokumentować kod w Visual Studio dla innych osób. Jednak jak w ogóle dokumentacja ta działa.

 

 

Plik XML

Opisy metod i klas nie są definiowane wewnątrz bibliotek , są one definiowane w pliku XML z tym samą nazwą co biblioteka. Plik ten jest tworzony na podstawie naszych komentarzy w kodzie źródłowym. Visual Studio używa pliku XML aby wgrać właśnie te rzeczy. Te informacje nie są dostępne w bibliotece więc nie można ich pobrać przez .NET reflector.

/// <summary> 
/// Potęguje podaną liczbę. 
/// </summary> 
public static int Power(this int i)

Kompilator c#  widząc komentarze w naszym kodzie generuje ten właśnie plik XML. Później Visual Studio sprawdza czy istnieje plik XML powiązany z daną biblioteką i wyświetla  do niej odpowiedni opis.

Jak można dostać się do tego pliku. Programuje już jakiś czas i nie widziałem takich plików xml w katalogach. Logicznie myśląc na pewno musi być jakaś opcja, która blokuje mi zobaczenie tego pliku i miałem rację.

Gdzie jest ten plik xml w opcjach Visual Studio

Tak jak to widać na powyższymi obrazku w oknie opcji projektu w zakładce “bulid” mam do dyspozycji checkbox  z opcją czy chcemy mieć dostęp do tego pliku xml. Struktura pliku xml z projektu , którym testowałem prostą metodę rozszerzającą (o czy w ty wpisie) wygląda następująco.

<?xml version="1.0"?> 
<doc> 
   <assembly> 
       <name>ConsoleExtensionMethod</name> 
   </assembly> 
    <members> 
            <member name="M:ConsoleExtensionMethod.MyTool.Power(System.Int32)"> 
                     <summary> Metoda rozszerzeniowa.
            Potęguje podaną liczbę.
                      </summary> 
                      <param name="i">liczba</param> 
                      <returns>power</returns> 
            </member> 
     </members> 
</doc>

Struktura tego pliku nie wydaje się być skomplikowana ,ale modyfikowanie tego pliku mija się z celem. Z drugiej mam dostęp do naszych komentarzy stworzonych w Visual Studio po za Visual Studio.

Wiedząc już, jak działa ta dokumentacją/komentarze kodu zacząłem myśleć jakie są zaawansowane narzędzia do ich używania. O tym  w tym wpisie.