Antworten:
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.
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<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.
Führen Sie XML-Kommentare wie folgt durch
/// <summary>
/// This does something that is awesome
/// </summary>
public void doesSomethingAwesome() {}///<param name="paramName">Tralala</param>
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.
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 :)
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)
{
}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;
}Lesen Sie http://msdn.microsoft.com/en-us/library/3260k4x7.aspx Wenn Sie nur die Kommentare angeben, werden die Hilfekommentare in Intellisense nicht angezeigt.
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.
Außerdem versucht das Visual Studio-Add-In-Ghost-Dokument, die Header-Kommentare aus Ihrem Funktionsnamen zu erstellen und auszufüllen.
Solmead hat die richtige Antwort. Weitere Informationen finden Sie unter XML-Kommentare .