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

Visual Studio может помочь вам документировать элементы кода, такие как классы и методы, автоматически формируя стандартную структуру комментариев для XML-документации. Во время компиляции можно создать XML-файл, содержащий комментарии для документации. Чтобы включить этот параметр, выберите Generate a file containing API documentation (Создать файл, содержащий документацию по API) на вкладке Сборка>Выходные данные в свойствах проекта.

Совет

Если вы хотите настроить нестандартное имя и расположение для файла документации, добавьте свойство DocumentationFile в файл .csproj, .vbproj или .fsproj.

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

Примечание.

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

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

  1. Поместите текстовый курсор над элементом, например методом, который нужно задокументировать.

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

    • Введите /// в C# или ''' в Visual Basic

    • В меню Правка выберите IntelliSense>Вставить комментарий.

    • Щелкните правой кнопкой мыши или вызовите контекстное меню в редакторе кода или над ним и выберите Фрагмент кода>Вставить комментарий.

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

    XML comment template - C#

    XML comment template - Visual Basic

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

    Screenshot showing the completed comment.

Стили можно использовать в комментариях XML, которые будут отображаться в виде кратких сведений при наведении указателя мыши на элемент. К этим стилям относятся курсив, полужирный шрифт, маркеры и ссылка, доступная для щелчка.

Screenshot showing the completed comment with style tags for italics, bold, bullets, and a clickable link.

Примечание.

Существует параметр для переключения комментариев XML-документации после ввода /// в C# или ''' Visual Basic. В строке меню выберите Сервис>Параметры, чтобы открыть диалоговое окно Параметры. Затем перейдите к текстовому редактору >C# (или Visual Basic). > В разделе Справка редактора найдите параметр Создавать комментарии XML-документации.

См. также