Was ist der Zweck der Bemerkungen Tag in C#

Question

Ich verstehe, dass Bemerkungen Tag wird verwendet, um zusätzliche Informationen über die Klasse, aber es wird nicht intellisense angezeigt, während Hovering/Aufruf dieser Klasse. Ich würde gerne wissen wo genau es sinnvoll ist?

Answer 1

Bemerkungen werden zum Erstellen einer Dokumentationsdatei verwendet. Sie werden für detailliertere Kommentare verwendet, indem dem Tag "Zusammenfassung" zusätzliche Informationen hinzugefügt werden (das Tag "Zusammenfassung" wird in IntelliSense angezeigt).

Die generierte Dokumentationsdatei wird im XML-Format vorliegen.

Um die Dokumentationsdatei zu generieren, müssen Sie die Compileroption "/ doc" hinzufügen. In Visual Studio können Sie die Generierung von XML-Dokumentationsdatei durch aktivieren: Name

1. Rechts klicken Projekt -> Eigenschaften
2. Go Registerkarte Build
3. aktivieren (überprüfen), Option die XML-Dokumentationsdatei

Answer 2

Viele Tags in .NET werden beim Generieren von Dokumentation wirklich genutzt. Vielleicht am populärsten und eins, das ich benutze, ist Sandcastle.

Hier ist eine ziemlich alte Blog-Post zu diskutieren das Thema, aber Sie werden den Punkt.

„Die meisten Entwickler Ich denke, kennen das Konzept der XML-Code Kommentare mit .NET-Objekten dekorieren Es sind wirklich zwei Vorteile: 1) Es zeigt diese Informationen in Intellisense, wenn Sie das Objekt konsumieren und 2) Sie können Dokumentation der Produktionskomponente wie MSDN. "

Quelle: XML Code Comments and Sandcastle, demystified!

Answer 3

die Tags von Visual Studio verwendet werden IntelliSense Hinweise über die Klassen, Funktionen zu geben und Eigenschaften, die Sie erstellen, wenn sie ordnungsgemäß erstellt werden, wie folgt:

In C# (und mit Visual Studio-Code-Editor) dies ist einfach durch Eingabe von /// (drei Schrägstriche anstelle von zwei) und drücken Sie Return.

Das wird "XML-Kommentare" erstellen und die am häufigsten verwendeten Tags für Sie hinzufügen (zum Beispiel Parameter-Tags für jeden Parameter Ihrer Methode).
Wenn sich der Cursor über der Klasse befindet, wird ein <summary>-Tag erstellt. Wenn es über einer Methode liegt, werden zusätzlich <param> Tags für jeden Parameter und eine <returns>-Variable für den Rückgabewert erstellt.

Andere, wie <remarks> werden dann von IntelliSense vorgeschlagen, während sich der Cursor innerhalb der /// Kommentare befindet (siehe Beispiel unten). Nach meinem Wissen werden nur <summary> und <param> Tags von IntelliSense verwendet. Wenn eines dieser Tags ein cref-Attribut enthält, können Sie auf andere Elemente verweisen (wie im Beispiel gezeigt).

Zusätzlich, wie die anderen Antworten erklären, können Sie eine XML-Dokumentation erstellen, die in ein Hyperlink-Dokument oder statische HTML-Dateien mithilfe von Drittanbieter-Tools konvertiert werden kann.

Beispiel:

/// <summary> 
/// Description what the class does 
/// </summary> 
public class MyClass 
{ 
    /// <summary> 
    /// Description what the function does 
    /// </summary> 
    /// <param name="param1">Description what the parameter does 
    /// Optional tags inside param1: 
    /// <c></c> <code></code> <list type=""></list> <paramref name="param1"/> 
    /// <para></para> 
    /// </param> 
    /// <param name="param2">Description what the parameter does</param> 
    /// <returns>Description about the return value</returns> 
    public string MyMethod(int param1, string param2) 
    { 
     return "Some value: " + MyProperty; 
    } 

    /// <summary> 
    /// Description what the property does 
    /// </summary> 
    /// <see cref="MyMethod(int, string)"/> 
    string MyProperty { get; set; } 

    // optional tags (valid for class and methods): 

    /// <completionlist cref=""/> 
    /// <example></example> 
    /// <exception cref=""></exception> 
    /// <include file='' path='[@name=""]'/> 
    /// <permission cref=""></permission> 
    /// <remarks></remarks> 
    /// <see cref=""/> 
    /// <seealso cref=""/> 
}