Как закомментировать в xml файле

Содержание
  1. Комментарии XML-документации
  2. Создание выходных данных XML-документации
  3. Формат комментариев XML
  4. Средства, принимающие входные данные XML-документации
  5. Строки идентификаторов
  6. Спецификация языка C#
  7. Как я могу прокомментировать одну строку в XML?
  8. Правила синтаксиса XML
  9. Все XML элементы должны иметь закрывающий тег
  10. Теги XML регистрозависимы
  11. XML элементы должны соблюдать корректную вложенность
  12. У XML документа должен быть корневой элемент
  13. XML пролог
  14. Значения XML атрибутов должны заключаться в кавычки
  15. Сущности
  16. Комментарии в XML
  17. В XML пробелы сохраняются
  18. В XML новая строка сохраняется как LF
  19. Синтаксически верный XML документ
  20. Примеры комментариев к XML-документации
  21. Документирование класса, структуры или интерфейса
  22. Документирование иерархии классов и интерфейсов
  23. Универсальные типы
  24. Пример класса Math
  25. Практическое руководство. Вставка XML-комментариев для создания документации
  26. Вставка XML-комментариев для элемента кода

Комментарии XML-документации

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

Благодаря этому процессу добавление документации по API в код предоставляет множество преимуществ:

Такие средства как Visual Studio предоставляют IntelliSense для многих распространенных XML-элементов, используемых в комментариях к документации.

В этой статье рассматриваются следующие темы:

Создание выходных данных XML-документации

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

Вы задаете параметр DocumentationFile или DocumentationFile, а компилятор находит все поля комментариев с XML-тегами в исходном коде и создает XML-файл документации на основе этих комментариев. Если этот параметр включен, компилятор создаст предупреждение CS1591 для любого открытого видимого члена, объявленного в проекте без комментариев XML-документации.

Формат комментариев XML

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

Visual Studio автоматически вставляет теги и и устанавливает курсор между ними после ввода разделителя /// в редакторе кода. Вы можете включить или отключить эту функцию в диалоговом окне «Параметры».

Компилятор обнаруживает в начале второй и третьей строки общий шаблон » * «. Шаблон не включается в выходные данные.

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

Компилятор не обнаруживает шаблон в следующем комментарии по двум причинам. Во-первых, количество пробелов перед звездочкой не является одинаковым в разных строках. Во-вторых, пятая строка начинается с символа табуляции, который не является пробелом. Весь текст из строк со второй по пятую обрабатывается как часть комментария.

Для ссылки на XML-элементы (например, если функция обрабатывает определенные XML-элементы, которые требуется включить в комментарии XML-документации) можно использовать стандартный механизм заключения в скобки ( и > ). Для ссылки на универсальные идентификаторы в элементах ссылок кода ( cref ) можно использовать escape-символы (например, cref=»List » ) или фигурные скобки ( cref=»List» ). В особом случае компилятор анализирует фигурные скобки, как угловые, чтобы при ссылке на универсальные идентификаторы сделать комментарий документации менее громоздким.

Комментарии XML-документации не являются метаданными. Они не включаются в скомпилированную сборку, и поэтому не доступны посредством отражения.

Средства, принимающие входные данные XML-документации

Следующие средства создают выходные данные на основе XML-комментариев:

Строки идентификаторов

Компилятор соблюдает следующие правила при формировании строк идентификаторов.

В строке нет пробелов.

Первая часть строки определяет тип элемента, использующего один символ, за которым следует двоеточие. Используются следующие типы элементов.

Знак Тип члена Примечания
Нет namespace Вы не можете присвоить комментарий документации пространству имен, но можете создать для него cref-ссылку, если такие ссылки поддерживаются.
T type В качестве типа может использоваться класс, интерфейс, структура, перечисление или делегат.
C поле
С свойство; Включает индексаторы или другие индексированные свойства.
M method Включает специальные методы, такие как конструкторы и операторы.
E event
! текст ошибки Остальная часть строки предоставляет сведения об ошибке. Компилятор C# создает сведения об ошибках для ссылок, которые не могут быть разрешены.

Вторая часть строки содержит полное имя элемента, начиная от корня пространства имен. Имя элемента, включающие типы и пространства имен разделяются точками. Если в имени самого элемента есть точки, они заменяются символами решетки («#»). Предполагается, что в именах элементов не может содержаться символ решетки. Например, полное имя конструктора для объекта String имеет вид System.String.#ctor.

Только для операторов преобразования ( op_Implicit и op_Explicit ) возвращаемое значение метода кодируется как символ

Примеры ниже демонстрируют, как создаются строки идентификаторов для класса и его элементов.

Спецификация языка C#

Дополнительные сведения см. в приложении Спецификация языка C# в комментариях документации.

Источник

Как я могу прокомментировать одну строку в XML?

Это скорее проверка, которую нельзя пропустить.

Есть ли / нет строкового комментария в XML? Итак, один без доводчика, например «//», который использует компилятор.

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

Нет, нет возможности комментировать строку в XML и автоматически заканчивать комментарий на переносе строки.

Как уже говорили другие, в XML не существует легального способа сделать однострочный комментарий, который закомментировал бы несколько строк, но есть способы упростить комментирование сегментов XML.

Если посмотреть на приведенный ниже пример, если вы добавите ‘>’ в первую строку, XmlTag будет раскомментирован. Удалите ‘>’, и он снова закомментирован. Это самый простой из известных мне способов быстро комментировать / раскомментировать XML, не нарушая работу.

Дополнительным преимуществом является то, что вы управляете только верхним комментарием, а нижний комментарий может оставаться там вечно. Это нарушает совместимость с SGML, и некоторые синтаксические анализаторы XML не будут использовать его. Пока это не постоянное приспособление в вашем XML, и ваши парсеры принимают его, это не проблема.

Если вам важна совместимость с SGML, просто используйте вместо этого:

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

Источник

Правила синтаксиса XML

Правила синтаксиса XML крайне просты и логичны. Их легко запомнить и легко использовать.

Все XML элементы должны иметь закрывающий тег

В HTML некоторые элементы могут не иметь закрывающего тега:

В XML нельзя опускать закрывающий тег. Абсолютно все элементы должны закрываться:

Возможно, вы заметили из предыдущих примеров, что XML декларация не имеет закрывающего тега. Это не ошибка. Дело в том, что декларация не относится к XML документу, поэтому у нее и нет закрывающего тега.

Теги XML регистрозависимы

Открывающий и закрывающий теги должны определяться в одном регистре:

Замечание: «Открывающий и закрывающий теги» иногда еще называют «начальный и конечный теги». Используйте то определение, которое вам более симпатично. По сути это одно и то же.

XML элементы должны соблюдать корректную вложенность

В HTML иногда можно наблюдать такую картину:

и иногда это даже работает должным образом.

В XML все элементы обязаны соблюдать корректную вложенность:

Понятие «корректная вложенность» по отношению к приведенным примерам просто означает, что так как элемент открывается внутри элемента , то и закрываться он должен внутри элемента .

У XML документа должен быть корневой элемент

XML документ должен содержать один элемент, который будет родительским для всех других элементов. Он называется корневым элементом.

XML пролог

Следующая строка называется XML прологом:

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

В XML документе могут присутствовать международные символы, вроде русских букв, и чтобы не возникало ошибок необходимо указать кодировку, либо сохранить XML файл в формате UTF-8.

UTF-8 — кодировка XML документов по умолчанию.

Значения XML атрибутов должны заключаться в кавычки

Так же, как и в HTML, у XML элементов могут быть атрибуты в виде пары имя/значение.

В XML значения атрибутов должны заключаться в кавычки.

Посмотрите на следующие два примера XML документа. Первый с ошибкой, второй написан правильно:

Ошибка в первом XML документе заключается в том, что значение атрибута date элемента note не заключено в кавычки.

Сущности

Некоторые символы в XML имеют особые значения.

Если вы поместите, например, символ « > больше, чем & & амперсанд ‘ ‘ апостроф « « кавычки

Замечание: Только символы » » допустим, но лучше его всегда заменять на сущность.

Комментарии в XML

Синтаксис комментариев в XML такой же, как и в HTML.

Использование двух символов тире в середине комментария не допустимо.

Странно, но так можно:

В XML пробелы сохраняются

В HTML несколько последовательных пробельных символов усекаются до одного. В XML документе все пробельные символы сохраняются.

В XML новая строка сохраняется как LF

В приложениях Windows новая строка хранится в следующем виде: символ перевода каретки и символ новой строки (CR+LF).

Unix и Mac OSX используют LF.

Старые Mac системы используют CR.

XML сохраняет новую строку как LF.

Синтаксически верный XML документ

Если XML документ составлен в соответствии с приведенными синтаксическими правилами, то говорят, что это «синтаксически верный» XML документ.

Источник

Примеры комментариев к XML-документации

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

Документирование класса, структуры или интерфейса

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

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

Второй файл, xml_include_tag.xml, содержит комментарии к документации.

Документирование иерархии классов и интерфейсов

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

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

Используйте тег для описания параметров типа в универсальных типах и методах. Значение атрибута cref требует нового синтаксиса для ссылки на универсальный метод или класс:

Пример класса Math

В следующем коде показан реалистичный пример добавления комментариев к документу в библиотеку Math.

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

Источник

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

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

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

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

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

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

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

Введите /// в C# или »’ в Visual Basic

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

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

для каждого параметра и элемент для документирования возвращаемого значения.

doc preview cs

doc preview vb

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

doc result cs

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

doc style cs

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

Источник

Читайте также  Как выглядят конспекты по физике
admin
Своими силами
Adblock
detector