Рекомендуемые XML-теги для комментариев к документации по C#

Рекомендуемые XML-теги для комментариев к документации по C#

В комментариях к документации по C# используются XML-элементы, что позволяет определить структуру выходной документации. Одним из последствий использования этой функции является то, что в комментарии к документации можно добавить любой допустимый XML-код. Компилятор C# копирует эти элементы в выходной XML-файл. Несмотря на то что в комментариях (включая любой допустимый HTML-элемент) можно использовать любой допустимый XML-код, документирование кода рекомендуется по многим причинам.

Далее приводится ряд рекомендаций, распространенные сценарии использования и вопросы, которые нужно иметь в виду при работе с тегами XML-документации в коде C#. Несмотря на то что теги можно поместить в комментарии к документации, в этой статье описываются рекомендуемые теги для наиболее распространенных конструкций языка. Во всех случаях следует соблюдать следующие рекомендации:

  • Для обеспечения согласованности все открытые типы и их члены должны быть задокументированы.
  • Закрытые члены можно также задокументировать с помощью XML-комментариев. Однако это приводит к раскрытию внутренних (возможно, конфиденциальных) процессов библиотеки.
  • Как минимум, типы и их члены должен иметь тег <summary> , так как его содержимое требуется для IntelliSense.
  • Текст документации должны быть написан с использованием законченных предложений, в конце которых ставится точка.
  • Разделяемые классы полностью поддерживаются, и данные о документации объединяются в одну запись для этого типа.

Документация XML начинается с /// . При создании проекта шаблоны добавляют несколько строк /// . Обработка этих комментариев имеет некоторые ограничения.

  • Документация должна представлять собой XML с правильным форматом. Если XML сформирован неправильно, компилятор выдает предупреждение. Файл документации будет содержать комментарий, в котором сообщается, что обнаружена ошибка.
  • Некоторые рекомендуемые теги имеют особые значения.
    • Тег <param> используется для описания параметров. При использовании этого тега компилятор проверяет, что параметр существует и все параметры описаны в документации. При сбое проверки компилятор выдает предупреждение.
    • Атрибут cref может быть присоединен к любому тегу для ссылки на элемент кода. Компилятор проверяет наличие этого элемента кода. При сбое проверки компилятор выдает предупреждение. Компилятор учитывает любые операторы using при поиске типа, описанного в атрибуте cref .
    • Тег <summary> используется технологией IntelliSense в Visual Studio для отображения дополнительных сведений о типе или элементе.

    XML-файл не предоставляет полную информацию о типе и членах (например, он не содержит никаких сведений о типе). Чтобы получить полную информацию о типе или элементе, используйте файл документации вместе с отражением для текущего типа или элемента.

    Некоторые из рекомендуемых тегов можно использовать для любого элемента языка. Другие имеют более специализированное использование. Наконец, некоторые теги используются для форматирования текста в документации. В этой статье описываются рекомендуемые теги, упорядоченные по их использованию.

    Компилятор проверяет синтаксис элементов, за которыми следует один символ * в следующем списке. Visual Studio предоставляет IntelliSense для тегов, проверенных компилятором, и всех тегов, за которыми следует * * в следующем списке. Помимо указанных здесь тегов, компилятор и Visual Studio проверяют теги <b> , <i> , <u> , <br/> и <a> . Компилятор также проверяет <tt> , который является устаревшим тегом HTML.

      , используемые для нескольких элементов. Эти теги являются минимальным набором для любого API.
        : значение этого элемента отображается в IntelliSense в Visual Studio. **
        : значение этого элемента отображается в IntelliSense в Visual Studio. *: Значение этого элемента отображается в IntelliSense в Visual Studio. * : значение этого элемента отображается в IntelliSense в Visual Studio.
        ** *
        * *
        *: Значение этого элемента отображается в IntelliSense в Visual Studio.

      Комментарии документации не применяются к пространству имен.

      Чтобы ввести в текст комментария документации угловые скобки, используйте для символов < и > коды HTML &lt; и &gt; соответственно. Это показано в следующем примере.

      Общие теги

      <summary>

      Тег <summary> следует использовать для описания типа или элемента типа. Используйте Примечания > , чтобы добавить дополнительные сведения в описание типа. Чтобы включить средства документации, такие как DocFX и Sandcastle, для создания внутренних гиперссылок на страницы документации для элементов кода, используйте атрибут cref. Текст в теге <summary> является единственным источником сведений о типе для технологии IntelliSense и также отображается в окне обозревателя объектов.

      <remarks>

      <remarks> Тег используется для добавления сведений о типе или члене типа, дополняя сведения, указанные в <remarks> . Эти сведения отображаются в окне "Обозреватель объектов". Этот тег может содержать более длинные объяснения. Возможно, вы обнаружите, что использование разделов CDATA для разметки упрощает написание. Такие средства, как docfx , обрабатывают текст Markdown в разделах.

      Члены документа

      <returns>

      Тег <returns> следует использовать в комментариях к объявлению метода для описания возвращаемого значения.

      <param>
      • name : имя параметра метода. Имя заключается в двойные кавычки (" "). Имена параметров должны соответствовать сигнатуре API. Если один или несколько параметров не охвачены, компилятор выдает предупреждение. Компилятор также выдает предупреждение, если значение name не соответствует формальному параметру в объявлении метода.

      Тег <param> следует использовать в комментариях к объявлению метода для описания одного из параметров такого метода. Чтобы задокументировать несколько параметров, используйте несколько тегов <param> . Текст тега <param> отображается в IntelliSense, обозревателе объектов и веб-отчете по комментариям к коду.

      <paramref>
      • name : имя параметра, на который указывается ссылка. Имя заключается в двойные кавычки (" ").

      Тег <paramref> позволяет указать, что слово в комментариях к коду, например в блоке <summary> или <remarks> , ссылается на параметр. В XML-файл такое слово может выделяться особым образом, например курсивом или полужирным шрифтом.

      <exception>
      • cref : ссылка на исключение, которое доступно из текущей среды компиляции. Компилятор проверяет, существует ли исключение, и приводит member к каноническому имени элемента в выходных XML-данных. member необходимо заключать в двойные кавычки (" ").

      Тег <exception> служит для указания возможных исключений. Этот тег может применяться к определениям методов, свойств, событий и индексаторов.

      <value>

      Тег <value> позволяет описывать значение, которое представляется свойством. при добавлении свойства с помощью мастера кода в среде разработки Visual Studio .net он добавляет тег сводки > для нового свойства. Следует вручную добавить тег <value> для описания значения, которое представляется свойством.

      Форматирование выходных данных документации

      <para> Тег предназначен для использования внутри тега, например <para> , <или >, и позволяет добавлять в текст структуру. Тег <para> создает абзац с двойным отступом. Используйте тег <br/> , если хотите добавить в него один абзац.

      Блок <listheader> используется для определения строки заголовка в таблице или списке определений. При определении таблицы необходимо ввести данные для term в заголовке. Каждый элемент в списке указывается в блоке <item> . При создании списка определений необходимо указать одновременно term и description . Тем не менее для таблицы, маркированного или нумерованного списка достаточно ввести только description . Число блоков <item> в списке или таблице не ограничено.

      С помощью тега <c> можно указать, что текст в описании необходимо пометить как код. Используйте код > , чтобы указать несколько строк в виде кода.

      Тег <code> используется для указания нескольких строк кода. Используйте c > , чтобы указать, что однострочный текст в описании должен быть помечен как код.

      <example>

      Тег <example> позволяет указать пример использования метода или другого элемента библиотеки. Пример обычно включает использование тега Code > .

      Повторное использование текста документации

      <инхеритдок>

      Наследование XML-комментариев от базовых классов, интерфейсов и аналогичных методов. Использование inheritdoc позволяет обойтись без копирования и вставки одинаковых XML-комментариев и автоматически поддерживать их синхронизацию. Обратите внимание, что при добавлении тега <inheritdoc> к типу все члены также будут наследовать эти комментарии.

      • cref : Укажите участника, из которого следует наследовать документацию. Унаследованные теги не переопределяют уже определенные теги для текущего элемента.
      • path : запрос с выражением XPath, в результате которого выводится набор узлов. С помощью этого атрибута можно отфильтровать теги, которые следует включить в наследуемую документацию или исключить из нее.

      Добавьте XML-комментарии в базовые классы или интерфейсы, и InheritDoc скопирует их во все реализации классов. Добавьте XML-комментарии в синхронные методы, и InheritDoc скопирует их в асинхронные версии аналогичных методов. Если нужно скопировать комментарии из определенного элемента, укажите нужный элемент в атрибуте cref .

      <include>
      • filename : имя XML-файла, содержащего документацию. Имя файла может быть квалифицировано с помощью относительного пути к файлу исходного кода. filename необходимо заключать в одинарные кавычки (' ').
      • tagpath : путь тегов в filename , который ведет к тегу name . Путь необходимо заключать в одинарные кавычки (' ').
      • name : спецификатор имени в теге, предшествующий комментариям. name будет иметь идентификатор id .
      • id : идентификатор тега, который предшествует комментариям. Идентификатор заключается в двойные кавычки (" ").

      Тег <include> позволяет задать ссылку на комментарии в другом файле, которые описывают типы и элементы вашего исходного кода. Включение внешнего файла является альтернативой размещению комментариев документации непосредственно в файле исходного кода. Помещая комментарии документации в отдельный файл, вы можете реализовать управление их версиями отдельно от версий исходного кода. В этом случае файл исходного кода может быть извлечен для изменения одним пользователем, а файл документации — другим. Тег <include> использует XML-синтаксис XPath. Сведения об использовании тега <include> см. в документации по XPath.

      Создание ссылок и гиперссылок

      • cref="member" : ссылка на член или поле, которые доступны для вызова из текущей среды компиляции. Компилятор проверяет, существует ли элемент кода, и передает member в имя элемента в выходных XML-данных. member необходимо заключать в двойные кавычки (" "). Можно указать другой текст ссылки для "cref", используя отдельный закрывающий тег.
      • href="link" : гиперссылка на заданный URL-адрес. Например, <see href="https://github.com">GitHub</see> формирует гиперссылку с текстом GitHub, которая ведет на сайт https://github.com .
      • langword="keyword" : Ключевое слово языка, например true или одно из других допустимых langword="keyword" .

      Тег <see> позволяет задать ссылку из текста. Используйте seeAlso > , чтобы указать, что текст следует поместить в раздел "см. также". Используйте атрибут cref для создания внутренних гиперссылок на страницы документации для элементов кода. Вы включаете параметры типа, чтобы указать ссылку на универсальный тип или метод, например cref="IDictionary" . Кроме того, href является допустимым атрибутом, который будет функционировать как гиперссылка.

      <seealso>
      • cref="member" : ссылка на член или поле, которые доступны для вызова из текущей среды компиляции. Компилятор проверяет, существует ли элемент кода, и передает member в имя элемента в выходных XML-данных. member необходимо заключать в двойные кавычки (" ").
      • href="link" : гиперссылка на заданный URL-адрес. Например, <seealso href="https://github.com">GitHub</seealso> формирует гиперссылку с текстом GitHub, которая ведет на сайт https://github.com .

      <seealso> Тег позволяет указать текст, который может потребоваться отобразить в разделе " <seealso> ". Используйте Просмотр > , чтобы указать ссылку в тексте. Тег seealso нельзя вложить в тег summary .

      Атрибут cref

      cref Атрибут в теге XML-документации означает "ссылка на код". Он указывает, что внутренний текст тега является элементом кода, таким как тип, метод или свойство. Средства работы с документацией, такие как DocFX и Sandcastle , используют атрибуты для автоматического создания гиперссылок на страницу, где задокументированы тип или член.

      Атрибут href

      Атрибут href означает ссылку на веб-страницу. Его можно использовать для прямой ссылки на интерактивную документацию по API или библиотеке.

      Универсальные типы и методы

      <typeparam>
      • TResult : имя параметра типа. Имя заключается в двойные кавычки (" ").

      Тег <typeparam> следует использовать в комментариях к объявлению универсального типа или метода для описания параметра типа. Добавьте такой тег для каждого параметра типа универсального типа или метода. Текст для тега <typeparam> будет отображаться в IntelliSense.

      <typeparamref>
      • TKey : имя параметра типа. Имя заключается в двойные кавычки (" ").

      Используйте этот тег, чтобы разрешить получателям файла документации форматировать слово определенным образом, например курсивным шрифтом.

      Пользовательские теги

      Все описанные выше теги распознаются компилятором C#. Тем не менее пользователь может определять собственные теги. Такие средства, как Sandcastle, обеспечивают поддержку дополнительных тегов, таких как событие > и >, и даже поддерживают <. Средства создания пользовательской или внутренней документации также можно использовать со стандартными тегами. Кроме того, поддерживается несколько выходных форматов — от HTML до PDF.