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

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

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

Примечание.

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

Включение создания документации

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

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

Кроме того, можно добавить свойства GenerateDocumentationFile или DocumentationFile в ФАЙЛ CSPROJ, VBPROJ или FSPROJ . Установите для GenerateDocumentationFile true создания файла документации с именем и расположением по умолчанию. DocumentationFile Используйте свойство, чтобы указать другое имя или расположение.

Если вы используете DocumentationFile самостоятельно или с GenerateDocumentationFile заданным trueсвойством, создается файл документации с указанным именем и расположением. Однако если задано GenerateDocumentationFile falseзначение, файл документации не создается, даже если задано 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 панель "Быстрая информация" отображается следующим образом:

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

• Комментарии для документации
• XML-документация в Visual Basic
• Комментарии (C++)
• Документация XML (Visual C++)
• Создание кода