Compartilhar via

Como escrever documentos bons /// para referência da API do .NET

O objetivo final dos documentos da API do .NET é fazer com que os /// comentários XML no código-fonte do .NET sejam a "fonte da verdade". Para MSBuild, ASP.NET Core e EF Core, essa meta foi atendida. No entanto, atualmente, o repositório dotnet-api-docs continua sendo a fonte da verdade para alguns namespaces na referência da API do .NET. Esse problema de dotnet/runtime acompanha o esforço para retroportar documentos do .NET e tornar o repositório do dotnet/runtime a fonte de verdade. A presença ou ausência do botão "editar" em uma página geralmente indica que o dotnet-api-docs repositório é a fonte da verdade. Se estiver faltando, a fonte da verdade provavelmente será os /// comentários no repositório de origem.

Este artigo fornece dicas sobre como escrever bons comentários de documento dentro do próprio código-fonte.

Comentários bem feitos resultam em bons documentos

Os comentários de barra tripla da API do .NET são transformados em documentação pública no site learn.microsoft.com e também aparecem no IntelliSense no IDE. Os comentários devem ser:

  • Completo – entradas de documento vazias para métodos, parâmetros, exceções e assim por diante, fazem com que as APIs se sintam sub-compatíveis, temporárias ou triviais.
  • Correto: os leitores verificam detalhes críticos e ficam frustrados quando as informações principais estão ausentes ou incorretas.
  • Contextual — os leitores entram nessa página na pesquisa e precisam saber como e quando usar a API e quais são as implicações do código.
  • Polido – gramática e ortografia pobres ou precipitadas podem confundir o leitor e tornar até mesmo instruções simples ambíguas; além disso, a apresentação ruim sugere baixo investimento.

Práticas recomendadas

  1. Use cref em vez de href para vincular a outro tipo ou método.

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

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

  2. Ao referenciar parâmetros, encapsule o nome do parâmetro em uma <paramref> marca, por exemplo, The offset in <paramref name="source" /> where the range begins..

  3. Se você tiver mais de um parágrafo no comentário do documento, separe os parágrafos com <para> marcas.

  4. Encapsular exemplos de código em <code> marcas dentro <example> de marcas.

  5. Use <seealso> para adicionar links a outras APIs na seção "Ver Também" gerada automaticamente.

Marcas de documento XML

Etiqueta Propósito Exemplo
<altmember> Adiciona um link "Veja também" à API especificada. <altmember cref="System.Console.Out" />
<c> Formata o texto especificado como código dentro de uma descrição. Gets the current version of the language compiler, in the form <c>Major.Minor.Revision.Build</c>.
<code> Formata várias linhas como código. <code language="csharp">using(logger.BeginScope("Processing request from {Address}", address)) { }</code>
<example> Adiciona um exemplo de código no título "Exemplo" H2. <example><code language="csharp">using(logger.BeginScope("Processing request from {Address}", address)) { }</code></example>
<exception> Descreve uma exceção que a API pode gerar. <exception cref="T:System.ArgumentException">No application identity is specified in <paramref name="identity" />.</exception>
<include> Consulte comentários em outro arquivo que descreva as APIs em seu código-fonte. <include file="../docs/AbsoluteLayout.xml" path="Type[@FullName='Microsoft.Maui.Controls.AbsoluteLayout']/Docs/*" />

Exemplo de MAUI do .NET
<inheritdoc> Herda comentários XML de classes base, interfaces e métodos semelhantes. <inheritdoc />
<list> Cria uma lista numerada ou com marcadores. <list type="bullet"><item><description>Set the root path to the result.</description></item><item><description>Load host configuration.</description></item></list>
<para> Separa parágrafos.
<paramref> Refere-se a um parâmetro de método. Returns the activity with the specified <paramref name="id" />.
<related> Adiciona um link "Veja também" ao artigo especificado. <related type="Article" href="/dotnet/framework/ado-net-overview">ADO.NET overview</related>
<see cref> Links para outra API. Describes the behavior that caused a <see cref="Scroll" /> event.
<see langword> Formata o texto especificado como código. Gets the value of the <see langword="Accept-Ranges" /> header for an HTTP response.
<seealso> Adiciona um link "Veja também" à API especificada. <seealso cref="T:System.Single" />
<typeparamref> Refere-se a um parâmetro de tipo. The <typeparamref name="THandler" /> is resolved from a scoped service provider.

Para obter mais informações, consulte as marcas XML recomendadas para C# e a especificação C#. A especificação ECMAXML também possui boas informações, embora seja importante estar ciente de que há algumas diferenças entre os comentários de documentação /// e ECMAXML (por exemplo, os alvos cref são totalmente expandidos e possuem prefixos no ECMAXML).

Referências cruzadas

Quando você usa uma <see cref> marca para vincular a outra API, não é necessário adicionar um prefixo ao nome do tipo, como T: para o tipo ou M: para o método. Na verdade, a regra de análise de código CA1200 sinaliza comentários de código que adicionam um prefixo ao nome do tipo em uma marca cref. No entanto, há algumas exceções a esta regra:

  • Quando você deseja vincular à forma geral de um método que tem mais de uma sobrecarga, o compilador C# atualmente não dá suporte a isso. A solução alternativa para documentos é prefixar o nome O: do método no código-fonte (ou Overload: em ECMAXML) e suprimir a regra CA1200. Por exemplo: <altmember cref="O:System.Diagnostics.Process.Kill" />.
  • Quando a API não pode ser resolvida a partir do contexto atual, que inclui quaisquer using diretivas. Nesse caso, use o nome da API totalmente qualificado com um prefixo.

Quando a <see cref> marca é convertida em ECMAXML, o mdoc substitui o nome do tipo pelo DocId completo da API, que inclui um prefixo.

Descrições

Para obter diretrizes autoritativas sobre como descrever cada tipo de símbolo e suas várias partes, consulte o wiki de documentos da API do .NET.

Comentários vazios

O texto de espaço reservado conhecido para comentários vazios é To be added.. O sistema de build do Learn reconhece esse texto e o remove quando o ECMAXML é convertido em HTML, deixando uma descrição vazia.

Arquivos de código separados

Se o exemplo de código for longo, você poderá colocá-lo em um arquivo separado no repositório de documentos e vinculá-lo a ele do código-fonte da seguinte maneira:

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

Para obter mais detalhes sobre como conectar arquivos de código separados, consulte esta discussão.

Atributos de linguagem

Atributos de linguagem em <code> marcas são opcionais, mas fazem com que o código seja formatado com codificação de cores. Por exemplo:

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

APIs internas

Ao documentar uma API que não se destina a ser usada pelos consumidores, use texto semelhante ao seguinte:

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

Consulte também

  • Last updated on