Wstaw komentarze XML do generowania dokumentacji

W tym artykule opisano, jak program Visual Studio może pomóc w dokumentowaniu elementów kodu, takich jak klasy i metody, automatycznie generując standardową strukturę komentarzy dokumentacji XML. W czasie kompilacji można wygenerować plik XML zawierający komentarze do dokumentacji.

Plik XML wygenerowany przez kompilator można dystrybuować wraz z zestawem .NET, aby program Visual Studio i inne środowiska IDE mogły używać funkcji IntelliSense do wyświetlania szybkich informacji o typach i elementach członkowskich. Możesz również uruchomić plik XML za pomocą narzędzi, takich jak DocFX i Sandcastle , aby wygenerować witryny internetowe referencyjne interfejsu API.

Uwaga

Polecenie Wstaw komentarz w celu automatycznego wstawiania struktury komentarzy dokumentacji XML jest dostępne w językach C# i Visual Basic. W przypadku języka C++możesz ręcznie wstawić komentarze dokumentacji XML i nadal generować pliki dokumentacji XML w czasie kompilacji.

Włączanie generowania dokumentacji

Aby włączyć generowanie dokumentacji, zaznacz pole wyboru Wygeneruj plik zawierający dokumentację interfejsu API na karcie Kompiluj>dane wyjściowe we właściwościach projektu.

Domyślnie plik dokumentacji o nazwie taki sam jak zestaw z rozszerzeniem pliku .xml jest generowany w tym samym katalogu co zestaw. Jeśli chcesz skonfigurować nazwę inną niżdefault lub lokalizację pliku, wprowadź lub przejdź do alternatywnej lokalizacji w obszarze ścieżka pliku dokumentacji XML.

Alternatywnie można dodać właściwości GenerateDocumentationFile lub DocumentationFile do pliku csproj, vbproj lub fsproj. Ustaw GenerateDocumentationFile wartość , aby true wygenerować plik dokumentacji z domyślną nazwą i lokalizacją. DocumentationFile Użyj właściwości , aby określić inną nazwę lub lokalizację.

Jeśli używasz DocumentationFile jej samodzielnie lub z GenerateDocumentationFile właściwością ustawioną na true, zostanie wygenerowany plik dokumentacji o określonej nazwie i lokalizacji. Jeśli jednak ustawiono GenerateDocumentationFilefalsewartość , nie zostanie wygenerowany żaden plik dokumentacji, nawet jeśli ustawisz DocumentationFile właściwość .

Włączanie skrótu klawiaturowego wstawiania komentarzy

Możesz ustawić opcję Komentarze , aby automatycznie wstawić struktury komentarzy XML po wpisaniu /// w języku C# lub ''' Visual Basic.

1. Na pasku menu programu Visual Studio wybierz pozycję Narzędzia>Opcje.
2. W oknie dialogowym Opcje przejdź do pozycji Edytor>tekstu C# (lub Visual Basic) >Advanced.
3. W sekcji Komentarze wybierz lub usuń zaznaczenie pozycji Wygeneruj komentarze dokumentacji XML dla \\\ (lub "").

Automatyczne wstawianie komentarza XML

1. W programie Visual Studio umieść kursor nad elementem, który chcesz udokumentować, na przykład metodę.

2. Przeprowadź jedną z następujących czynności:

   • Jeśli jest włączony skrót do wstawiania automatycznego komentarza, wpisz /// w języku C# lub ''' w Visual Basic.
   • Z menu Edycja wybierz pozycję IntelliSense>Wstaw komentarz.
   • W menu kontekstowym lub prawym przyciskiem myszy wybierz pozycję Wstaw komentarz fragmentu kodu>.

   Struktura komentarzy XML jest natychmiast generowana powyżej elementu kodu. Na przykład podczas komentowania następującej GetUserName metody szablon generuje <summary> element, <param> element parametru i <returns> element do dokumentowania wartości zwracanej.

   /// <summary>
   /// 
   /// </summary>
   /// <param name="id"></param>
   /// <returns></returns>
   public string GetUserName(int id)
   {
       return "username";
   }
   

   ''' <summary>
   ''' 
   ''' </summary>
   ''' <param name="id"></param>
   ''' <returns></returns>
   Public Function GetUserName(id As Integer) As String
       Return "username"
   End Function
   

3. Wprowadź opisy dla każdego elementu XML, aby w pełni udokumentować kod. Na przykład:

    /// <summary>
    /// Gets the username associated with the specified ID.
    /// </summary>
    /// <param name="id">The unique user ID.</param>
    /// <returns>A string containing the username for the specified ID.</returns>
    public string GetUserName(int id)
    {
        return "username";
    }
   

Elementy i style XML można używać w komentarzach renderowanych w szybkich informacjach po umieszczeniu wskaźnika myszy na kodzie. Te elementy obejmują kursywę lub pogrubienie style, listy punktowane lub numerowane oraz klikalne cref lub href linki.

Na przykład wprowadź następujący kod w pliku programu w języku C#:

/// <summary>
/// There are two <see href="https://bing.com">params</see>.
/// <list type="number">
/// <item><param name="id">The user <em>id</em></param></item>
/// <item><param name="username">The user <em>name</em></param></item>
/// </list>
/// </summary>
/// <returns>The <strong>username</strong>.</returns>
public static string GetUserName(int id)
{
    return "username";
}

Po umieszczeniu wskaźnika myszy nad pozycją GetUserName okienko Szybkich informacji jest wyświetlane w następujący sposób:

Powiązana zawartość

• Komentarze dokumentacji
• Dokumentacja XML w Visual Basic
• Komentarze (C++)
• Dokumentacja XML (Visual C++)
• Generowanie kodu