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.
Wie kann ich das für Funktionen und Eigenschaften haben, die ich schreibe?
Was Sie brauchen, sind XML-Kommentare - im Grunde folgen sie dieser Syntax (wie von Solmead vage beschrieben):
C #
VB
quelle
<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.
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.
quelle
Führen Sie XML-Kommentare wie folgt durch
quelle
///<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.
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.
quelle
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 :)
quelle
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:
Ich habe dann die drei /// davor gestellt und Visual Studio hat mir folgendes gegeben:
quelle
Definieren Sie Methoden wie diese und Sie erhalten die Hilfe, die Sie benötigen.
Screenshot der Codeverwendung
quelle
Lesen Sie http://msdn.microsoft.com/en-us/library/3260k4x7.aspx Wenn Sie nur die Kommentare angeben, werden die Hilfekommentare in Intellisense nicht angezeigt.
quelle
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 EinstellungAdvanced
>Generate XML documentation comments for '''
. Aktivieren Sie für C # die EinstellungAdvanced
>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 -/doc
Option. 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.
quelle
Außerdem versucht das Visual Studio-Add-In-Ghost-Dokument, die Header-Kommentare aus Ihrem Funktionsnamen zu erstellen und auszufüllen.
quelle
Solmead hat die richtige Antwort. Weitere Informationen finden Sie unter XML-Kommentare .
quelle