Поделиться через

Вставка XML-комментариев для создания документации

В этой статье описывается, как Visual Studio помогает документировать такие элементы кода, как классы и методы, автоматически создавая стандартную структуру комментариев xml-документации. Во время компиляции можно создать XML-файл, содержащий комментарии документации.

XML-файл, созданный компилятором, можно распространять вместе со сборкой .NET, чтобы Visual Studio и другие интегрированные среды разработки могли использовать IntelliSense для отображения быстрых сведений о типах и членах. Вы также можете запустить XML-файл с помощью таких средств, как DocFX и Sandcastle , чтобы создать справочные веб-сайты API.

Замечание

Команда insert Comment для автоматической вставки структуры комментариев XML-документации доступна в C# и Visual Basic. Для C++можно вручную вставить комментарии xml-документации и по-прежнему создавать XML-файлы документации во время компиляции.

Включение генерации документации

Чтобы включить создание документации, установите флажок "Создать файл, содержащий документацию API" на вкладке "Сборка"> и "Вывод" свойств проекта.

По умолчанию файл документации с таким же именем, как у вашей сборки, и расширением .xml создается в том же каталоге, что и сборка. Если вы хотите задать другое, отличное от стандартного, имя или местоположение для файла, введите или укажите альтернативное местоположение в разделе Путь к файлу XML документации.

Кроме того, можно добавить свойства GenerateDocumentationFile или DocumentationFile в файл .csproj, .vbproj или .fsproj. Установите GenerateDocumentationFile на true, чтобы создать файл документации с именем и расположением по умолчанию. DocumentationFile Используйте свойство, чтобы указать другое имя или расположение.

Если вы используете DocumentationFile по отдельности или с GenerateDocumentationFile свойством, установленным на true, создается файл документации с указанным именем и расположением. Однако, если задано значение GenerateDocumentationFilefalse, файл документации не создается, даже если установлено свойство DocumentationFile.

Включить сочетание клавиш для вставки комментариев

Можно задать параметр "Примечания ", чтобы автоматически вставлять структуры комментариев XML после ввода /// в C# или ''' Visual Basic.

  1. В строке меню Visual Studio выберите "Параметры инструментов>".
  2. В диалоговом окне Параметры перейдите к Текстовый редактор>C# (или Visual Basic) >Дополнительно.
  3. В разделе "Комментарии" выберите или отмените выбор Создать примечания к XML-документации для \\\ (или ''').

Автоматическое вставка xml-комментария

  1. В Visual Studio поместите курсор над элементом, который требуется документировать, например метод.

  2. Выполните одно из следующих действий:

    • Если включена функция автоматической вставки комментариев, введите /// в C# или ''' в Visual Basic.
    • В меню "Изменить" выберите IntelliSense>Insert Comment.
    • В контекстном меню щелкните правой кнопкой мыши или выберите фрагмент>вставить комментарий.

    Структура комментариев XML немедленно создается над элементом кода. Например, при комментировании следующего GetUserName метода шаблон создает <summary> элемент, <param> элемент параметра и <returns> элемент для документирования возвращаемого значения.

    /// <summary>
/// 
/// </summary>
/// <param name="id"></param>
/// <returns></returns>
public string GetUserName(int id)
{
    return "username";
}

    ''' <summary>
''' 
''' </summary>
''' <param name="id"></param>
''' <returns></returns>
Public Function GetUserName(id As Integer) As String
    Return "username"
End Function

  3. Введите описания для каждого XML-элемента, чтобы полностью документировать код. Рассмотрим пример.

     /// <summary>
 /// Gets the username associated with the specified ID.
 /// </summary>
 /// <param name="id">The unique user ID.</param>
 /// <returns>A string containing the username for the specified ID.</returns>
 public string GetUserName(int id)
 {
     return "username";
 }

При наведении указателя мыши на код можно использовать XML-элементы и стили в комментариях, которые отображаются в кратких сведениях. К этим элементам относятся курсив или полужирные стили, маркированные или нумерованные списки, а также кликабельные ссылки cref или href.

Например, введите следующий код в файл программы C#:

/// <summary>
/// There are two <see href="https://bing.com">params</see>.
/// <list type="number">
/// <item><param name="id">The user <em>id</em></param></item>
/// <item><param name="username">The user <em>name</em></param></item>
/// </list>
/// </summary>
/// <returns>The <strong>username</strong>.</returns>
public static string GetUserName(int id)
{
    return "username";
}

При наведении указателя мыши на GetUserName панель "Быстрая информация" отображается следующим образом:

Снимок экрана: завершенный комментарий с тегами стиля для ссылки, нумерованного списка и курсивного и полужирного форматирования.

Связанный контент

  • Last updated on