Compartir a través de

Cómo escribir una buena documentación /// para la referencia de la API de .NET

El objetivo final de los documentos de la API de .NET es que los comentarios /// XML en el código fuente de .NET sean el "origen de la verdad". Para MSBuild, ASP.NET Core y EF Core, se ha cumplido este objetivo. Sin embargo, actualmente el repositorio dotnet-api-docs sigue siendo el origen de la verdad para la referencia de la API principal de .NET. Este problema de dotnet/runtime realiza un seguimiento del esfuerzo para retrotraer documentos de .NET y convertir el repositorio dotnet/runtime en el origen de la verdad.

En este artículo se proporcionan sugerencias sobre cómo escribir buenos comentarios de documentos en el propio código fuente.

Los buenos comentarios hacen buenos documentos

Los comentarios de barra triple de la API de .NET se transforman en documentación pública en learn.microsoft.com y aparecen en IntelliSense en el IDE. Los comentarios deben ser:

  • Completado: entradas de documento vacías para métodos, parámetros, excepciones, etc., hacer que las API se sientan poco compatibles, temporales o triviales.
  • Correcto: los lectores buscan detalles críticos y se frustran cuando falta información clave o es incorrecta.
  • Contextual: los lectores llegan a esta página desde la búsqueda y necesitan saber cómo y cuándo usar la API y cuáles son las implicaciones del código.
  • Pulido: una gramática pobre o una ortografía deficiente puede confundir al lector y hacer ambiguas incluso las llamadas más simples; además, la mala presentación comunica una inversión baja.

procedimientos recomendados

  1. Use cref en lugar de href para vincular a otro tipo o método.

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

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

  2. Al hacer referencia a parámetros, encapsula el nombre del parámetro en una <paramref> etiqueta, por ejemplo, The offset in <paramref name="source" /> where the range begins..

  3. Si tiene más de un párrafo en el comentario del documento, separe los párrafos con <para> etiquetas.

  4. Envuelve los ejemplos de código en las etiquetas <code> dentro de las etiquetas <example>.

  5. Use <seealso> para agregar vínculos a otras API en la sección "Ver también" generada automáticamente.

Etiquetas de documento XML

Etiqueta Propósito Ejemplo
<altmember> Agrega un vínculo "Ver también" a la API especificada. <altmember cref="System.Console.Out" />
<c> Da formato al texto especificado como código dentro de una descripción. Gets the current version of the language compiler, in the form <c>Major.Minor.Revision.Build</c>.
<code> Da formato a varias líneas como código. <code language="csharp">using(logger.BeginScope("Processing request from {Address}", address)) { }</code>
<example> Agrega un ejemplo de código en el encabezado "Ejemplo" H2. <example><code language="csharp">using(logger.BeginScope("Processing request from {Address}", address)) { }</code></example>
<exception> Describe una excepción que puede producir la API. <exception cref="T:System.ArgumentException">No application identity is specified in <paramref name="identity" />.</exception>
<include> Consulte los comentarios de otro archivo que describen las API en el código fuente. <include file="../docs/AbsoluteLayout.xml" path="Type[@FullName='Microsoft.Maui.Controls.AbsoluteLayout']/Docs/*" />

Ejemplo de MAUI de .NET
<inheritdoc> Hereda comentarios XML de clases base, interfaces y métodos similares. <inheritdoc />
<list> Crea una lista numerada o con viñetas. <list type="bullet"><item><description>Set the root path to the result.</description></item><item><description>Load host configuration.</description></item></list>
<para> Separa párrafos.
<paramref> Hace referencia a un parámetro de método. Returns the activity with the specified <paramref name="id" />.
<related> Agrega un vínculo "Ver también" al artículo especificado. <related type="Article" href="/dotnet/framework/ado-net-overview">ADO.NET overview</related>
<see cref> Vínculos a otra API. Describes the behavior that caused a <see cref="Scroll" /> event.
<see langword> Da formato al texto especificado como código. Gets the value of the <see langword="Accept-Ranges" /> header for an HTTP response.
<seealso> Agrega un vínculo "Ver también" a la API especificada. <seealso cref="T:System.Single" />
<typeparamref> Hace referencia a un parámetro de tipo. The <typeparamref name="THandler" /> is resolved from a scoped service provider.

Para obtener más información, vea Etiquetas XML recomendadas para C# y la especificación de C#. La especificación ECMAXML también tiene buena información, aunque tenga en cuenta que hay algunas diferencias entre los comentarios de documentación de ECMAXML y /// (por ejemplo, los destinos cref se expanden completamente y tienen prefijos en ECMAXML).

Referencias cruzadas

Cuando se usa una <see cref> etiqueta para vincular a otra API, no es necesario agregar un prefijo al nombre de tipo, como T: para el tipo o M: para el método . De hecho, la regla de análisis de código CA1200 marca los comentarios de código que agregan un prefijo al nombre de tipo en una cref etiqueta. Sin embargo, hay un par de excepciones a esta regla:

  • Si desea vincular a la forma general de un método que tiene más de una sobrecarga, el compilador de C# no lo admite actualmente. La solución alternativa para los documentos es prefijar el nombre del método con O: en el código fuente (o Overload: en ECMAXML) y suprimir la regla CA1200. Por ejemplo: <altmember cref="O:System.Diagnostics.Process.Kill" />.
  • Cuando la API no se puede resolver desde el contexto actual, lo que incluye cualquier using directiva. En este caso, use el nombre completo de la API con un prefijo.

Cuando la <see cref> etiqueta se convierte en ECMAXML, mdoc reemplaza el nombre de tipo por el DocId completo de la API, que incluye un prefijo.

Descripciones

Para obtener instrucciones autoritativas sobre cómo describir cada tipo de símbolo y sus distintas partes, consulte la wiki de documentación de la API de .NET.

Comentarios vacíos

El texto del marcador de posición conocido para los comentarios vacíos es To be added.. El sistema de compilación de Learn reconoce este texto y lo quita cuando ECMAXML se convierte en HTML, dejando una descripción vacía.

Separar archivos de código

Si el ejemplo de código es largo, puede colocarlo en un archivo independiente en el repositorio de documentos y vincularlo desde el código fuente de la siguiente manera:

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

Para obtener más detalles sobre cómo enlazar archivos de código independientes, consulte esta explicación.

Atributos de lenguaje

Los atributos de lenguaje de las <code> etiquetas son opcionales, pero hacen que el código tenga el formato de codificación de colores. Por ejemplo:

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

Al documentar una API que no está pensada para que la usen los consumidores, use palabras similares a las siguientes:

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

Consulte también