Dela via

Så här skriver du bra ///-dokument för .NET API-referens

Det ultimata målet för .NET API-dokument är att /// XML-kommentarerna i .NET-källkoden ska vara "sanningskällan". För MSBuild, ASP.NET Core och EF Core har det här målet uppnåtts. Men för närvarande är lagringsplatsen dotnet-api-docs fortfarande sanningskällan för vissa namnområden i .NET API-referensen. Det här dotnet/runtime-problemet spårar arbetet med att backporta .NET-dokument och göra dotnet/runtime-lagringsplatsen till sanningskällan. Förekomsten eller frånvaron av knappen "redigera" på en sida anger ofta att dotnet-api-docs lagringsplatsen är källan till sanningen. Om den saknas är sanningskällan sannolikt /// kommentarerna i källdatabasen.

Den här artikeln innehåller tips om hur du skriver bra dokumentkommentare i själva källkoden.

Bra kommentarer leder till bra dokument

.NET API-kommentarer med tre snedstreck omvandlas till offentlig dokumentation på learn.microsoft.com och visas även i IntelliSense i IDE. Kommentarerna bör vara:

  • Slutför – tomma dokumentposter för metoder, parametrar, undantag och så vidare gör att API:erna känns ouppbackade, provisoriska eller triviala.
  • Rätt – läsarna söker efter viktig information och blir frustrerade när viktig information saknas eller är felaktig.
  • Kontextuell – läsarna hamnar på den här sidan från sökningen och behöver veta hur och när API:et ska användas och vilka kodkonsekvenserna är.
  • Polerad – dålig eller hastig grammatik och stavning kan förvirra läsaren och göra även enkla anrop tvetydiga; dålig presentation förmedlar också låga investeringar.

Metodtips

  1. Använd cref i stället href för att länka till en annan typ eller metod.

    Rätt: <param name="configFile">An <see cref="XmlConfigResource" /> object.</param>

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

  2. När du refererar till parametrar omsluter du parameternamnet i en <paramref> tagg, The offset in <paramref name="source" /> where the range begins.till exempel .

  3. Om du har mer än ett stycke i dokumentkommenten separerar du styckena med <para> taggar.

  4. Omslut kodexempel med <code>-taggar inom <example>-taggar.

  5. Använd <seealso> för att lägga till länkar till andra API:er i avsnittet "Se även" automatiskt.

XML-dokumenttaggar

Etikett Avsikt Exempel
<altmember> Lägger till en "Se även"-länk till det angivna API:et. <altmember cref="System.Console.Out" />
<c> Formaterar den angivna texten som kod i en beskrivning. Gets the current version of the language compiler, in the form <c>Major.Minor.Revision.Build</c>.
<code> Formaterar flera rader som kod. <code language="csharp">using(logger.BeginScope("Processing request from {Address}", address)) { }</code>
<example> Lägger till ett kodexempel under rubriken "Exempel" H2. <example><code language="csharp">using(logger.BeginScope("Processing request from {Address}", address)) { }</code></example>
<exception> Beskriver ett undantag som API:et kan utlösa. <exception cref="T:System.ArgumentException">No application identity is specified in <paramref name="identity" />.</exception>
<include> Se kommentarer i en annan fil som beskriver API:erna i källkoden. <include file="../docs/AbsoluteLayout.xml" path="Type[@FullName='Microsoft.Maui.Controls.AbsoluteLayout']/Docs/*" />

.NET MAUI-exempel
<inheritdoc> Ärv XML-kommentarer från basklasser, gränssnitt och liknande metoder. <inheritdoc />
<list> Skapar en punktlista eller numrerad lista. <list type="bullet"><item><description>Set the root path to the result.</description></item><item><description>Load host configuration.</description></item></list>
<para> Separerar paragrafer.
<paramref> Refererar till en metodparameter. Returns the activity with the specified <paramref name="id" />.
<related> Lägger till länken "Se även" i den angivna artikeln. <related type="Article" href="/dotnet/framework/ado-net-overview">ADO.NET overview</related>
<see cref> Länkar till ett annat API. Describes the behavior that caused a <see cref="Scroll" /> event.
<see langword> Formaterar den angivna texten som kod. Gets the value of the <see langword="Accept-Ranges" /> header for an HTTP response.
<seealso> Lägger till en "Se även"-länk till det angivna API:et. <seealso cref="T:System.Single" />
<typeparamref> Refererar till en typparameter. The <typeparamref name="THandler" /> is resolved from a scoped service provider.

Mer information finns i Rekommenderade XML-taggar för C# och C#-specifikationen. ECMAXML-specifikationen har också bra information, även om du är medveten om att det finns vissa skillnader mellan ECMAXML- och ///-dokumentationskommentarna (till exempel utökas cref-målen fullständigt och har prefix i ECMAXML).

Korsreferenser

När du använder en tagg för att länka till ett <see cref> annat API behöver du inte lägga till ett prefix i typnamnet, till exempel T: för typ eller M: metod. Faktum är att kodanalysregeln CA1200 flaggar kodkommentare som lägger till ett prefix i typnamnet i en cref tagg. Det finns dock några undantag till den här regeln:

  • När du vill länka till den allmänna formen av en metod som har mer än en överlagring stöder C#-kompilatorn för närvarande inte det. Lösningen för dokument är att prefixa metodnamnet med O: i källkoden (eller Overload: i ECMAXML) och undertrycka regeln CA1200. Till exempel: <altmember cref="O:System.Diagnostics.Process.Kill" />.
  • När API:et inte kan lösas från den aktuella kontexten, som inkluderar någon using direktiv. I det här fallet använder du det fullständigt kvalificerade API-namnet med ett prefix.

När taggen <see cref> konverteras till ECMAXML ersätter mdoc typnamnet med det fullständiga DocId för API:et, som innehåller ett prefix.

Beskrivningar

Auktoritativa riktlinjer för att beskriva varje symboltyp och dess olika delar finns i wikin för .NET API-dokument.

Tomma kommentarer

Den välkända platshållartexten för tomma kommentarer är To be added.. Learn-byggsystemet känner igen den här texten och tar bort den när ECMAXML konverteras till HTML, vilket lämnar en tom beskrivning.

Separata kodfiler

Om kodexemplet är långt kan du placera det i en separat fil i docs-lagringsplatsen och länka till den från källkoden på följande sätt:

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

Mer information om hur du ansluter separata kodfiler finns i den här diskussionen.

Språkattribut

Språkattribut på <code> taggar är valfria, men de gör att koden formateras med färgkodning. Till exempel:

/// <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>

Interna API:er

När du dokumenterar ett API som inte är avsett att användas av konsumenter använder du formuleringar som liknar följande:

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

Se även

  • Last updated on