Как написать хорошие документы /// для справочника по API .NET

Конечная цель документации по API .NET заключается в том /// , чтобы xml-комментарии в исходном коде .NET были "источником истины". Для MSBuild ASP.NET Core и EF Core эта цель выполнена. Однако в настоящее время репозиторий dotnet-api-docs остается источником истины для некоторых пространств имен в справочнике по API .NET. Эта проблема dotnet/runtime отслеживает усилия, чтобы вернуть документы .NET и сделать репозиторий dotnet/runtime источником истины. Наличие или отсутствие кнопки "Изменить" на странице часто указывает, что dotnet-api-docs репозиторий является источником истины. Если он отсутствует, то единственным источником правды, скорее всего, являются комментарии в исходном репозитории ///.

В этой статье приводятся советы по написанию хороших комментариев к документу в самом исходном коде.

Хорошие комментарии способствуют созданию хороших документов

Комментарии API .NET, начинающиеся с трех слэшей, преобразуются в общедоступную документацию на сайте learn.microsoft.com и отображаются в IntelliSense в интегрированной среде разработки. Примечания должны быть следующими:

• Полный — пустые записи в документации для методов, параметров, исключений и других элементов делают API менее поддержанными, временными или тривиальными.
• Правильно— читатели сканируют критически важные сведения и становятся разочарованы, когда ключевые сведения отсутствуют или некорректны.
• Читатели, приходящие на эту страницу из поиска, должны знать, как и когда использовать API, а также какое влияние это окажет на код.
• Отшлифованный — бедная или поспешная грамматика и орфография могут запутать читателя и сделать даже простые обращения неоднозначными; кроме того, плохое оформление указывает на низкую степень вложенности.

Лучшие практики

1. Используйте cref вместо href ссылки на другой тип или метод.

   Правильно: <param name="configFile">An <see cref="XmlConfigResource" /> object.</param>

   Неправильный: <param name="configFile">An <a href="https://learn.Microsoft.com/{path}/XmlConfigResource"></a> object.</param>

2. При ссылке на параметры переключите имя параметра в <paramref> тег, например The offset in <paramref name="source" /> where the range begins..

3. Если в комментарии документа есть несколько абзацев, разделите абзацы тегами <para> .

4. Примеры кода помещаются в теги <code>, заключённые в теги <example>.

5. Используйте <seealso>, чтобы добавить ссылки на другие API-интерфейсы в автогенерированном разделе "См. также".

Теги документов XML

Дополнительные сведения см. в разделе "Рекомендуемые XML-теги для C# " и спецификации C#. Спецификация ECMAXML также имеет хорошую информацию, хотя имейте в виду, что существуют некоторые различия между ECMAXML и /// комментариями документации (например, целевые объекты cref полностью развернуты и имеют префиксы в ECMAXML).

Перекрестные ссылки

При использовании тега <see cref> для ссылки на другой API нет необходимости добавлять префикс в имя типа, например T: для типа или M: метода. На самом деле правило анализа кода CA1200 помечает комментарии кода, добавляющие префикс в имя типа в cref теге. Однако существует несколько исключений для этого правила:

• Если вы хотите сделать ссылку на общую форму метода с несколькими перегрузками, компилятор C# на данный момент этого не поддерживает. Решением для документов является префикс имени метода в O: исходном коде (или Overload: в ECMAXML) и подавление правила CA1200. Например: <altmember cref="O:System.Diagnostics.Process.Kill" />.
• Если спрогнозировать API из текущего контекста, который включает в себя любую using директиву, не удается. В этом случае используйте полное имя API с префиксом.

<see cref> При преобразовании тега в ECMAXML mdoc заменяет имя типа полным идентификатором DOCId API, который включает префикс.

Описания

Достоверные рекомендации по описанию каждого типа символов и его различных частей см. в документации по API .NET.

Пустые комментарии

Хорошо известный текст-заполнитель для пустых комментариев — это To be added.. Система сборки Learn распознает этот текст и удаляет его при преобразовании ECMAXML в HTML, оставляя пустое описание.

Отдельные файлы кода

Если пример кода является длинным, его можно поместить в отдельный файл в репозитории документов и связать с ним из исходного кода следующим образом:

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

Дополнительные сведения о том, как подключить отдельные файлы кода, см. в этом обсуждении.

Атрибуты языка

Атрибуты языка для <code> тегов являются необязательными, но они вызывают форматирование кода с помощью цветового кодирования. Рассмотрим пример.

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

При документировании API, который не предназначен для использования потребителями, используйте формулировки, аналогичные приведённым ниже.

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

См. также

• Формат ECMAXML
• Рекомендуемые XML-теги для C#
• Комментарии документации (спецификация C#)