Condividi tramite

Come scrivere documenti /// validi per le informazioni di riferimento sulle API .NET

L'obiettivo finale della documentazione dell'API .NET consiste nell'avere i commenti /// XML nel codice sorgente .NET come "origine della verità". Per MSBuild, ASP.NET Core ed EF Core, questo obiettivo è stato raggiunto. Tuttavia, attualmente il repository dotnet-api-docs rimane la fonte autorevole delle informazioni sulle API di base di .NET. Questo problema dotnet/runtime tiene traccia dello sforzo necessario per eseguire il backporting della documentazione .NET e rendere il repository dotnet/runtime la fonte principale di riferimento.

Questo articolo fornisce suggerimenti sulla scrittura di commenti di documenti validi all'interno del codice sorgente stesso.

Buoni commenti per buoni documenti

I commenti a tripla barra dell'API .NET vengono trasformati in documentazione pubblica su learn.microsoft.com e vengono anche visualizzati in IntelliSense nell'IDE. I commenti devono essere:

  • Completa: voci di documenti vuote per metodi, parametri, eccezioni e così via, rendono le API non supportate, temporanee o semplici.
  • Risposta esatta: i lettori scandagliano i dettagli critici e diventano frustrati quando le informazioni chiave mancano o non sono corrette.
  • Contestuale: i lettori accedono a questa pagina dalla ricerca e devono sapere come e quando usare l'API e quali sono le implicazioni del codice.
  • Raffinato — grammatica e ortografia scadente o frettolosa possono confondere il lettore e rendere ambigue anche le chiamate più semplici; inoltre, una presentazione scadente comunica una scarsa attenzione.

Procedure consigliate

  1. Usare cref anziché href per collegarsi a un altro tipo o metodo.

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

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

  2. Quando si fa riferimento ai parametri, eseguire il wrapping del nome del parametro in un <paramref> tag, ad esempio The offset in <paramref name="source" /> where the range begins..

  3. Se nel commento del documento sono presenti più paragrafi, separare i paragrafi con <para> i tag.

  4. Includi gli esempi di codice nei tag <code> all'interno dei tag <example>.

  5. Usare <seealso> per aggiungere collegamenti ad altre API nella sezione "Vedere anche" generata automaticamente.

Tag della documentazione XML

Etichetta Scopo Esempio
<altmember> Aggiunge un collegamento "See also" all'API specificata. <altmember cref="System.Console.Out" />
<c> Formatta il testo specificato come codice all'interno di una descrizione. Gets the current version of the language compiler, in the form <c>Major.Minor.Revision.Build</c>.
<code> Formatta più righe come codice. <code language="csharp">using(logger.BeginScope("Processing request from {Address}", address)) { }</code>
<example> Aggiunge un esempio di codice sotto l'intestazione "Esempio" H2. <example><code language="csharp">using(logger.BeginScope("Processing request from {Address}", address)) { }</code></example>
<exception> Descrive un'eccezione che l'API può generare. <exception cref="T:System.ArgumentException">No application identity is specified in <paramref name="identity" />.</exception>
<include> Fare riferimento ai commenti in un altro file che descrivono le API nel codice sorgente. <include file="../docs/AbsoluteLayout.xml" path="Type[@FullName='Microsoft.Maui.Controls.AbsoluteLayout']/Docs/*" />

Esempio di MAUI .NET
<inheritdoc> Ereditare i commenti XML da classi di base, interfacce e metodi simili. <inheritdoc />
<list> Crea un elenco puntato o numerato. <list type="bullet"><item><description>Set the root path to the result.</description></item><item><description>Load host configuration.</description></item></list>
<para> Separa i paragrafi.
<paramref> Fa riferimento a un parametro del metodo. Returns the activity with the specified <paramref name="id" />.
<related> Aggiunge un collegamento "Vedere anche" all'articolo specificato. <related type="Article" href="/dotnet/framework/ado-net-overview">ADO.NET overview</related>
<see cref> Collegamenti a un'altra API. Describes the behavior that caused a <see cref="Scroll" /> event.
<see langword> Formatta il testo specificato come codice. Gets the value of the <see langword="Accept-Ranges" /> header for an HTTP response.
<seealso> Aggiunge un collegamento "See also" all'API specificata. <seealso cref="T:System.Single" />
<typeparamref> Fa riferimento a un parametro di tipo. The <typeparamref name="THandler" /> is resolved from a scoped service provider.

Per altre informazioni, vedere Tag XML consigliati per C# e specifica C#. La specifica ECMAXML include anche informazioni utili, anche se bisogna tenere presente che esistono alcune differenze tra ECMAXML e i commenti della documentazione /// (ad esempio, in ECMAXML le destinazioni cref sono completamente espanse e hanno prefissi).

Riferimenti incrociati

Quando si usa un <see cref> tag per collegarsi a un'altra API, non è necessario aggiungere un prefisso al nome del tipo, ad esempio T: per il tipo o M: per il metodo. In effetti, la regola di analisi del codice CA1200 contrassegna i commenti di codice che aggiungono un prefisso al nome del tipo in un cref tag. Tuttavia, esistono due eccezioni a questa regola:

  • Quando si vuole creare un collegamento alla forma generale di un metodo con più overload, il compilatore C# attualmente non lo supporta. La soluzione alternativa per la documentazione consiste nel anteporre il nome del metodo con O: nel codice sorgente (o Overload: in ECMAXML) e eliminare la regola CA1200. Ad esempio: <altmember cref="O:System.Diagnostics.Process.Kill" />.
  • Quando l'API non può essere risolta dal contesto corrente, che include qualsiasi direttiva using. In questo caso, usare il nome completo dell'API con un prefisso.

Quando il <see cref> tag viene convertito in ECMAXML, mdoc sostituisce il nome del tipo con il docId completo dell'API, che include un prefisso.

Descrizioni

Per linee guida autorevoli sulla descrizione di ogni tipo di simbolo e delle varie parti, vedere il wiki della documentazione dell'API .NET.

Commenti vuoti

Il testo segnaposto noto per i commenti vuoti è To be added.. Il sistema di compilazione Learn riconosce questo testo e lo rimuove quando ECMAXML viene convertito in HTML, lasciando una descrizione vuota.

Separare i file di codice

Se l'esempio di codice è lungo, è possibile inserirlo in un file separato nel repository docs e collegarlo al codice sorgente nel modo seguente:

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

Per altri dettagli su come associare file di codice separati, vedere questa discussione.

Attributi del linguaggio

Gli attributi del linguaggio nei <code> tag sono facoltativi, ma determinano la formattazione del codice con codifica a colori. Per esempio:

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

API interne

Quando si documenta un'API che non deve essere usata dai consumer, usare parole simili alle seguenti:

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

Vedere anche