Вставка 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 . Установите для GenerateDocumentationFiletrue создания файла документации с именем и расположением по умолчанию. 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 панель "Быстрая информация" отображается следующим образом:

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

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