Wie kann ich in IntelliSense Kommentare für Funktionen in Visual Studio abgeben?

139

Wenn Sie in Visual Studio und C # eine integrierte Funktion wie ToString () verwenden, wird in IntelliSense ein gelbes Feld angezeigt, in dem die Funktionsweise erläutert wird.

Alt-Text Alt-Text

Wie kann ich das für Funktionen und Eigenschaften haben, die ich schreibe?

Ali
quelle

Antworten:

215

Um einen Bereich zu generieren, in dem Sie eine Beschreibung für die Funktion und jeden Parameter für die Funktion angeben können, geben Sie Folgendes in die Zeile vor Ihrer Funktion ein und drücken Sie Enter:

  • C #: ///

  • VB: '''

Siehe Empfohlene Tags zu Dokumentation Kommentaren (C # Programming Guide) für weitere Informationen über die strukturierten Inhalte , die Sie in diesen Kommentaren enthalten.

Solmead
quelle
2
Hervorheben: Das ist ein dreifacher Schrägstrich in C ++ / C # (normale Kommentare sind doppelte Schrägstriche). Und in VB sind es zwei einfache Anführungszeichen, keine doppelten Anführungszeichen.
Abelenky
1
Es ist eigentlich drei einfache Anführungszeichen in vb
Joel Coehoorn
1
Tatsächlich sind es in VB 3 einfache Anführungszeichen: '' '
Hometoast
2
Alternativ können Sie in einer VB-Datei mit der rechten Maustaste auf eine Funktion oder Klasse klicken und auf "Kommentar einfügen" klicken. Für C # können Sie StyleCop verwenden, das Sie auffordert, gute Dokumentationsheader zu schreiben
user1069816
GhostDoc ist ein großartiges Tool, mit dem Sie einen Großteil des Textes in den Kommentaren hinzufügen können. submain.com/products/ghostdoc.aspx
Karl Gjertsen
74

Was Sie brauchen, sind XML-Kommentare - im Grunde folgen sie dieser Syntax (wie von Solmead vage beschrieben):

C #

///<summary>
///This is a description of my function.
///</summary>
string myFunction() {
     return "blah";
}

VB

'''<summary>
'''This is a description of my function.
'''</summary>
Function myFunction() As String
    Return "blah"
End Function
Tomas Aschan
quelle
23

<c>text</c>- Der Text, den Sie als Code angeben möchten.
Mit dem < c > -Tag können Sie angeben, dass Text in einer Beschreibung als Code markiert werden soll. Verwenden Sie < code >, um mehrere Zeilen als Code anzugeben.

<code>content</code>- Der Text, den Sie als Code markieren möchten.
Mit dem < code > -Tag können Sie mehrere Zeilen als Code angeben. Verwenden Sie < c >, um anzugeben, dass Text in einer Beschreibung als Code markiert werden soll.

<example>description</example>- Eine Beschreibung des Codebeispiels.
Mit dem Tag < example > können Sie ein Beispiel für die Verwendung einer Methode oder eines anderen Bibliotheksmitglieds angeben. Dies beinhaltet üblicherweise die Verwendung des < code > -Tags.

<exception cref="member">description</exception>- Eine Beschreibung der Ausnahme.
Mit dem Tag < Ausnahme > können Sie angeben, welche Ausnahmen ausgelöst werden können. Dieses Tag kann auf Definitionen für Methoden, Eigenschaften, Ereignisse und Indexer angewendet werden.

<include file='filename' path='tagpath[@name="id"]' />
Mit dem < include > -Tag können Sie auf Kommentare in einer anderen Datei verweisen, die die Typen und Elemente in Ihrem Quellcode beschreiben. Dies ist eine Alternative zum Platzieren von Dokumentationskommentaren direkt in Ihrer Quellcodedatei. Indem Sie die Dokumentation in einer separaten Datei ablegen, können Sie die Quellcodeverwaltung getrennt vom Quellcode auf die Dokumentation anwenden. Eine Person kann die Quellcodedatei auschecken lassen und eine andere Person kann die Dokumentationsdatei auschecken lassen. Das < include > -Tag verwendet die XML XPath-Syntax. In der XPath-Dokumentation finden Sie Möglichkeiten zum Anpassen Ihrer < Include > -Verwendung.

<list type="bullet" | "number" | "table">
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>term</term>
        <description>description</description>
    </item>
</list>

Der Block < listheader > wird verwendet, um die Überschriftenzeile einer Tabelle oder einer Definitionsliste zu definieren. Wenn Sie eine Tabelle definieren, müssen Sie nur einen Eintrag für den Begriff in der Überschrift angeben. Jedes Element in der Liste wird mit einem < Element > -Block angegeben. Beim Erstellen einer Definitionsliste müssen Sie sowohl den Begriff als auch die Beschreibung angeben. Für eine Tabelle, eine Liste mit Aufzählungszeichen oder eine nummerierte Liste müssen Sie jedoch nur einen Eintrag zur Beschreibung angeben. Eine Liste oder Tabelle kann beliebig viele < Element > -Blöcke enthalten.

<para>content</para>
Das < para > -Tag kann in einem Tag verwendet werden, z. B. < summary >, < remarks > oder < returns >, und Sie können dem Text Struktur hinzufügen.

<param name="name">description</param>
Das < param > -Tag sollte im Kommentar für eine Methodendeklaration verwendet werden, um einen der Parameter für die Methode zu beschreiben. Verwenden Sie mehrere < param > -Tags , um mehrere Parameter zu dokumentieren .
Der Text für das < param > -Tag wird in IntelliSense, im Objektbrowser und im Webbericht für Codekommentare angezeigt.

<paramref name="name"/>
Mit dem < paramref > -Tag können Sie angeben, dass ein Wort in den Codekommentaren , z. B. in einem < summary > - oder < remarks > -Block, auf einen Parameter verweist. Die XML-Datei kann verarbeitet werden, um dieses Wort auf unterschiedliche Weise zu formatieren, z. B. in Fettdruck oder Kursivschrift.

< permission cref="member">description</permission>
Die < Berechtigung > -Tag können Sie den Zugriff eines Mitglieds dokumentieren. Mit der PermissionSet-Klasse können Sie den Zugriff auf ein Mitglied angeben.

<remarks>description</remarks>
Das < remarks > -Tag wird verwendet, um Informationen zu einem Typ hinzuzufügen und die mit < summary > angegebenen Informationen zu ergänzen . Diese Informationen werden im Objektbrowser angezeigt.

<returns>description</returns>
Der < kehrt > Tag sollte im Kommentar verwendet wird für eine Methodendeklaration des Rückgabewert zu beschreiben.

<see cref="member"/>
Mit dem < see > -Tag können Sie einen Link aus dem Text heraus angeben. Verwenden Sie < seealso >, um anzugeben, dass Text in einem Abschnitt "Siehe auch" platziert werden soll. Verwenden Sie das Attribut cref, um interne Hyperlinks zu Dokumentationsseiten für Codeelemente zu erstellen.

<seealso cref="member"/>
Mit dem < seealso > -Tag können Sie den Text angeben, der möglicherweise in einem Abschnitt "Siehe auch" angezeigt werden soll . Mit < sehen > einen Link aus Text angeben.

<summary>description</summary>
Das < summary > -Tag sollte verwendet werden, um einen Typ oder ein Typmitglied zu beschreiben. Verwenden Sie < remarks >, um einer Typbeschreibung zusätzliche Informationen hinzuzufügen. Verwenden Sie das cref-Attribut, um Dokumentationstools wie Sandcastle zum Erstellen interner Hyperlinks zu Dokumentationsseiten für Codeelemente zu aktivieren. Der Text für das < summary > -Tag ist die einzige Informationsquelle über den Typ in IntelliSense und wird auch im Objektbrowser angezeigt.

<typeparam name="name">description</typeparam>
Das < typeparam > -Tag sollte im Kommentar für eine generische Typ- oder Methodendeklaration verwendet werden, um einen Typparameter zu beschreiben. Fügen Sie für jeden Typparameter des generischen Typs oder der generischen Methode ein Tag hinzu. Der Text für das < typeparam > -Tag wird in IntelliSense, dem Webbericht für den Objektbrowser-Codekommentar , angezeigt.

<typeparamref name="name"/>
Verwenden Sie dieses Tag, damit Benutzer der Dokumentationsdatei das Wort auf eine bestimmte Weise formatieren können, z. B. kursiv.

<value>property-description</value>
Mit dem Tag < wert > können Sie den Wert beschreiben, den eine Eigenschaft darstellt. Beachten Sie, dass beim Hinzufügen einer Eigenschaft über den Code-Assistenten in der Visual Studio .NET-Entwicklungsumgebung ein < summary > -Tag für die neue Eigenschaft hinzugefügt wird . Sie sollten dann manuell ein < value > -Tag hinzufügen , um den Wert zu beschreiben, den die Eigenschaft darstellt.

Max
quelle
11

Führen Sie XML-Kommentare wie folgt durch

/// <summary>
/// This does something that is awesome
/// </summary>
public void doesSomethingAwesome() {}
Michael Walts
quelle
6
Für Parameter hinzufügen:///<param name="paramName">Tralala</param>
The Oddler
10

Verwenden Sie ///, um jede Zeile des Kommentars zu beginnen, und lassen Sie den Kommentar die entsprechende XML für den Metadatenleser enthalten.

///<summary>
/// this method says hello
///</summary>
public void SayHello();

Obwohl ich persönlich glaube, dass diese Kommentare normalerweise falsch sind, es sei denn, Sie entwickeln Klassen, in denen der Code von seinen Verbrauchern nicht gelesen werden kann.

Entwicklung von Chris
quelle
2
Sie eignen sich gut für Erinnerungen an Verknüpfungen oder überall dort, wo Sie Bibliothekscode haben, in dem der Code möglicherweise lesbar ist, aber ein wenig zusätzliche Arbeit erforderlich ist, um darauf zuzugreifen.
Joel Coehoorn
1
Ich stimme Ihnen theoretisch zu, aber wenn Sie dieses Ghostdoc-Ding verwenden, erhöhen Sie das Rausch / Signal-Verhältnis so weit, dass der Rest der Kommentare nutzlos ist.
DevelopingChris
9

Diese werden als XML-Kommentare bezeichnet . Sie sind seit Ewigkeiten ein Teil von Visual Studio.

Sie können Ihren Dokumentationsprozess vereinfachen, indem Sie GhostDoc verwenden , ein kostenloses Add-In für Visual Studio, das XML-Dokumentkommentare für Sie generiert. Platzieren Sie einfach Ihr Caret auf der Methode / Eigenschaft, die Sie dokumentieren möchten, und drücken Sie Strg-Umschalt-D.

Hier ist ein Beispiel aus einem meiner Beiträge .

Hoffentlich hilft das :)

Igal Tabachnik
quelle
6

Wenn Sie in CSharp die Methoden- / Funktionskontur mit den Parms erstellen, werden beim Hinzufügen der drei Schrägstriche automatisch die Zusammenfassung und die Parms generiert.

Also habe ich eingegeben:

public string myMethod(string sImput1, int iInput2)
{
}

Ich habe dann die drei /// davor gestellt und Visual Studio hat mir folgendes gegeben:

/// <summary>
/// 
/// </summary>
/// <param name="sImput1"></param>
/// <param name="iInput2"></param>
/// <returns></returns>
public string myMethod(string sImput1, int iInput2)
{
}
Semperfi89
quelle
6

Definieren Sie Methoden wie diese und Sie erhalten die Hilfe, die Sie benötigen.

    /// <summary>
    /// Adds two numbers and returns the result
    /// </summary>
    /// <param name="first">first number to add</param>
    /// <param name="second">second number to </param>
    /// <returns></returns>
    private int Add(int first, int second)
    {
        return first + second;
    }

Screenshot der Codeverwendung

Empfange Yildiz
quelle
2

Alle diese anderen Antworten sind sinnvoll, aber unvollständig. Visual Studio verarbeitet XML-Kommentare, Sie müssen sie jedoch aktivieren. So geht's:

Intellisense verwendet XML-Kommentare, die Sie in Ihren Quellcode eingeben, diese müssen jedoch über Visual Studio-Optionen aktiviert sein. Zum Tools> Options> Text Editor. Aktivieren Sie für Visual Basic die Einstellung Advanced> Generate XML documentation comments for '''. Aktivieren Sie für C # die Einstellung Advanced> Generate XML documentation comments for ///. Intellisense verwendet die zusammenfassenden Kommentare, wenn sie eingegeben werden. Sie sind in anderen Projekten verfügbar, nachdem das referenzierte Projekt kompiliert wurde.

So erstellen Sie externe Dokumentation benötigen Sie eine XML - Datei durch die erzeugen Project Settings> Build> XML documentation file:Pfad , dass die Kontrollen der Compiler - /docOption. Sie benötigen ein externes Tool, das die XML-Datei als Eingabe verwendet und die Dokumentation in den von Ihnen gewählten Ausgabeformaten generiert.

Beachten Sie, dass das Generieren der XML-Datei Ihre Kompilierungszeit spürbar verlängern kann.

Suncat2000
quelle
1

Außerdem versucht das Visual Studio-Add-In-Ghost-Dokument, die Header-Kommentare aus Ihrem Funktionsnamen zu erstellen und auszufüllen.

Mark Rogers
quelle
0

Solmead hat die richtige Antwort. Weitere Informationen finden Sie unter XML-Kommentare .

Ed S.
quelle