So schreiben Sie gute ////-Dokumente für .NET-API-Referenz

Das ultimative Ziel für .NET-API-Dokumente besteht darin, dass die /// XML-Kommentare im .NET-Quellcode die "Quelle der Wahrheit" sein sollen. Für MSBuild, ASP.NET Core und EF Core wurde dieses Ziel erreicht. Derzeit bleibt das dotnet-api-docs-Repository jedoch die Quelle der Wahrheit für einige Namespaces in der .NET-API-Referenz. Dieses Dotnet/Runtime-Problem verfolgt den Aufwand zum Backport von .NET-Dokumenten und macht das dotnet/runtime Repo zur Quelle der Wahrheit. Das Vorhandensein oder Fehlen der Schaltfläche "Bearbeiten" auf einer Seite weist häufig darauf hin, dass das dotnet-api-docs Repository die Quelle der Wahrheit ist. Wenn es fehlt, ist die Quelle der Wahrheit wahrscheinlich die /// Kommentare im Quell-Repository.

Dieser Artikel enthält Tipps zum Schreiben guter Dokumentkommentare im Quellcode selbst.

Gute Kommentare führen zu guten Dokumenten

Triple-Slash-Kommentare der .NET-API werden in öffentliche Dokumentation auf der Website learn.microsoft.com umgewandelt und in IntelliSense in der IDE angezeigt. Die Kommentare sollten folgendes sein:

  • Vollständig – Leere Dokumenteinträge für Methoden, Parameter, Ausnahmen usw. lassen die APIs als mangelhaft unterstützt, provisorisch oder trivial erscheinen.
  • Richtig – Leser suchen nach wichtigen Details und werden frustriert, wenn wichtige Informationen fehlen oder falsch sind.
  • Kontextbezogene – Leser gelangen von der Suche auf diese Seite und müssen wissen, wie und wann die API verwendet werden soll und welche Codeauswirkungen sie haben.
  • Poliert – Schlechte oder hastige Grammatik und Rechtschreibung können den Leser verwirren und sogar einfache Aktionen mehrdeutig machen; außerdem vermittelt eine schlechte Präsentation einen geringen Einsatz.

Bewährte Methoden

  1. Verwenden Sie cref statt href, um einen anderen Typ oder eine andere Methode zu verwenden.

    Richtig: <param name="configFile">An <see cref="XmlConfigResource" /> object.</param>

    Falsch: <param name="configFile">An <a href="https://learn.Microsoft.com/{path}/XmlConfigResource"></a> object.</param>

  2. Wenn Sie auf Parameter verweisen, schließen Sie den Parameternamen in ein <paramref>-Tag ein, z. B. The offset in <paramref name="source" /> where the range begins..

  3. Wenn Sie mehrere Absätze im Dokumentkommentar haben, trennen Sie die Absätze durch <para> Tags.

  4. Umschließen Sie Codebeispiele mit <code>-Tags innerhalb von <example>-Tags.

  5. Verwenden Sie <seealso>, um Links zu anderen APIs im automatisch generierten Abschnitt "Siehe auch" hinzuzufügen.

XML-Dokumenttags

Etikett Zweck Beispiel
<altmember> Fügt der angegebenen API einen Link "Siehe auch" hinzu. <altmember cref="System.Console.Out" />
<c> Formatiert den angegebenen Text als Code in einer Beschreibung. Gets the current version of the language compiler, in the form <c>Major.Minor.Revision.Build</c>.
<code> Formatiert mehrere Zeilen als Code. <code language="csharp">using(logger.BeginScope("Processing request from {Address}", address)) { }</code>
<example> Fügt ein Codebeispiel unter der Überschrift "Beispiel" H2 hinzu. <example><code language="csharp">using(logger.BeginScope("Processing request from {Address}", address)) { }</code></example>
<exception> Beschreibt eine Ausnahme, die die API auslösen kann. <exception cref="T:System.ArgumentException">No application identity is specified in <paramref name="identity" />.</exception>
<include> Lesen Sie Kommentare in einer anderen Datei, die die APIs in Ihrem Quellcode beschreiben. <include file="../docs/AbsoluteLayout.xml" path="Type[@FullName='Microsoft.Maui.Controls.AbsoluteLayout']/Docs/*" />

.NET MAUI-Beispiel
<inheritdoc> Erben Sie XML-Kommentare von Basisklassen, Schnittstellen und ähnlichen Methoden. <inheritdoc />
<list> Erstellt eine Aufzählung oder nummerierte Liste. <list type="bullet"><item><description>Set the root path to the result.</description></item><item><description>Load host configuration.</description></item></list>
<para> Trennt Absätze.
<paramref> Verweist auf einen Methodenparameter. Returns the activity with the specified <paramref name="id" />.
<related> Fügt dem angegebenen Artikel einen Link "Siehe auch" hinzu. <related type="Article" href="/dotnet/framework/ado-net-overview">ADO.NET overview</related>
<see cref> Links zu einer anderen API. Describes the behavior that caused a <see cref="Scroll" /> event.
<see langword> Formatiert den angegebenen Text als Code. Gets the value of the <see langword="Accept-Ranges" /> header for an HTTP response.
<seealso> Fügt der angegebenen API einen Link "Siehe auch" hinzu. <seealso cref="T:System.Single" />
<typeparamref> Verweist auf einen Typparameter. The <typeparamref name="THandler" /> is resolved from a scoped service provider.

Weitere Informationen finden Sie unter Empfohlene XML-Tags für C# und die C#-Spezifikation. Die ECMAXML-Spezifikation enthält ebenfalls umfassende Informationen. Beachten Sie jedoch, dass es einige Unterschiede zwischen ECMAXML und der ///-Dokumentationskommentierung gibt (z. B. sind cref-Ziele vollständig erweitert und haben Präfixe in ECMAXML).

Querverweise

Wenn Sie ein <see cref> Tag verwenden, um eine Verknüpfung mit einer anderen API zu erstellen, muss dem Typnamen kein Präfix hinzugefügt werden, z T: . B. für typ oder M: für die Methode. Tatsächlich kennzeichnet die Codeanalyseregel CA1200 Codekommentare, die dem Typnamen in einem cref Tag ein Präfix hinzufügen. Es gibt jedoch einige Ausnahmen von dieser Regel:

  • Wenn Sie eine Verknüpfung mit der allgemeinen Form einer Methode herstellen möchten, die mehrere Überladungen aufweist, unterstützt der C#-Compiler dies derzeit nicht. Die Problemumgehung für Dokumente besteht darin, dem Methodennamen O: im Quellcode (oder Overload: in ECMAXML) voranzustellen und die Regel CA1200 zu unterdrücken. Beispiel: <altmember cref="O:System.Diagnostics.Process.Kill" />.
  • Wenn die API nicht aus dem aktuellen Kontext aufgelöst werden kann, das alle using Direktiven enthält. Verwenden Sie in diesem Fall den vollqualifizierten API-Namen mit einem Präfix.

Wenn das <see cref> Tag in ECMAXML konvertiert wird, ersetzt mdoc den Typnamen durch die vollständige DocId der API, die ein Präfix enthält.

Beschreibungen

Autoritative Richtlinien zum Beschreiben der einzelnen Symboltypen und ihrer verschiedenen Teile finden Sie im .NET-API-Dokumentationswiki.

Leere Kommentare

Der bekannte Platzhaltertext für leere Kommentare lautet To be added.. Das Buildsystem Learn erkennt diesen Text und entfernt ihn, wenn das ECMAXML in HTML konvertiert wird, wobei eine leere Beschreibung übrig bleibt.

Trennen von Codedateien

Wenn Ihr Codebeispiel langwierig ist, können Sie es in eine separate Datei im Docs-Repository einfügen und auf folgende Weise mit dem Quellcode verknüpfen:

/// <example>
/// <format type="text/markdown">
/// <![CDATA[
///  [!code-csharp[FieldAware](~/docs/samples/Microsoft.ML.Samples/Dynamic/FactorizationMachine.cs)]
/// ]]></format>
/// </example>

Weitere Informationen zum Verknüpfen separater Codedateien finden Sie in dieser Diskussion.

Sprachattribute

Sprachattribute für <code> Tags sind optional, führen jedoch dazu, dass der Code mit Farbcodierung formatiert wird. Beispiel:

/// <example>
/// This sample shows the basic pattern for defining a typed client class.
///   <code language="csharp">
///     class ExampleClient
///     {
///       private readonly HttpClient _httpClient;
///       private readonly ILogger _logger;
///
///       // Typed clients can use constructor injection to access additional services.
///       public ExampleClient(HttpClient httpClient, ILogger&lt;ExampleClient&gt; logger)
///       {
///         _httpClient = httpClient;
///         _logger = logger;
///       }
///     }
///   </code>
/// </example>

Interne APIs

Wenn Sie eine API dokumentieren, die nicht von Verbrauchern verwendet werden soll, verwenden Sie einen ähnlichen Wortlaut wie die folgenden:

<summary>This type supports the .NET infrastructure and is not intended to be used directly from your code.</summary>

Siehe auch

  • Last updated on