XML – Комментарии
В этой главе объясняется, как работают комментарии в документах XML. Комментарии XML похожи на комментарии HTML. Комментарии добавляются в виде примечаний или строк для понимания цели XML-кода.
Комментарии могут быть использованы для включения связанных ссылок, информации и терминов. Они видны только в исходном коде; не в коде XML. Комментарии могут появляться в любом месте XML-кода.
Синтаксис
XML-комментарий имеет следующий синтаксис –
Комментарий начинается с и заканчивается -> . Вы можете добавить текстовые заметки в качестве комментариев между персонажами. Вы не должны вкладывать один комментарий в другой.
пример
Следующий пример демонстрирует использование комментариев в документе XML –
Tanmay A
Любой текст между символами и -> считается комментарием.
Правила XML-комментариев
Следующие правила должны соблюдаться для XML-комментариев –
Комментарии в xml файле как делать
Вот код, который парсит, коменты не берет:
Function GetXmlFromString(s)
Set xmlDoc = CreateObject(«Microsoft.XMLDOM»)
If CaseIgnoreFind(Trim(s), » S_Parse = «» & s
Else
S_Parse = s
End If
xmlDoc.LoadXML (S_Parse) ‘From string
Set GetXmlFromString = xmlDoc
End Function
(12) это что за код? 🙂
что ты хочешь им сделать?
Может этот фрагмент что-то прояснит:
commentItem = xmlDoc.createComment(«Hello World!»);
xmlDoc.documentElement.appendChild(commentItem);
Проблемы невозможно решaть нa том же уровне компетентности, нa котором они возникaют. Альберт Эйнштейн
Комментарии в xml файле как делать
Просмотр профиля
28.9.2010, 9:25
Группа: Участник
Сообщений: 2003
Регистрация: 4.2.2008
Из: S-Petersburg
Пользователь №: 84
Репутация: 17
Как в XML-документе поставить строчный и многострочный комментарии? Спасибо.
P.S. Нашел, кажется. Начало . Вроде бы так?
Сообщение отредактировал AD — 28.9.2010, 9:32
опции профиля:
Комментарии XML-документации
В исходных файлах C# могут находиться структурированные комментарии, используемые для создания документации по API для типов, определенных в этих файлах. Компилятор C# создает файл XML, содержащий структурированные данные, представляющие комментарии и сигнатуры API. Другие средства могут обрабатывать эти выходные данные в формате XML и создавать удобочитаемую документацию, например, в виде веб-страниц или PDF-файлов.
Благодаря этому процессу добавление документации по API в код предоставляет множество преимуществ:
- Компилятор C# объединяет структуру кода C# и текст комментариев в XML-документ.
- Компилятор C# проверяет, соответствуют ли комментарии сигнатурам API для соответствующих тегов.
- Средства, обрабатывающие XML-файлы документации, могут определять XML-элементы и атрибуты, характерные для этих средств.
Такие средства как Visual Studio предоставляют IntelliSense для многих распространенных XML-элементов, используемых в комментариях к документации.
В этой статье рассматриваются следующие темы:
- Комментарии к документации и создание XML-файла
- Теги, проверяемые компилятором C# и Visual Studio
- Формат созданного XML-файла
Создание выходных данных XML-документации
Вы создаете документацию для кода, указывая ее в специальных полях комментариев, обозначаемых тройными косыми чертами. Поля комментария включают XML-элементы, которые описывают блок кода, следующий за комментариями. Пример:
/// /// This class performs an important function. /// public class MyClass <> Вы задаете параметр DocumentationFile или DocumentationFile, а компилятор находит все поля комментариев с XML-тегами в исходном коде и создает XML-файл документации на основе этих комментариев. Если этот параметр включен, компилятор создаст предупреждение CS1591 для любого открытого видимого члена, объявленного в проекте без комментариев XML-документации.
Формат комментариев XML
Для создания комментариев XML-документации необходимо использовать разделители, указывающие начало и конец комментария. С тегами в XML-документации можно использовать следующие разделители:
-
Однострочный разделитель /// : в примерах документации и шаблонах проектов C# используется эта форма. Если после разделителя указан пробел, он не включается в выходные данные XML.
Примечание Visual Studio автоматически вставляет теги
и устанавливает курсор между ними после ввода разделителя /// в редакторе кода. Вы можете включить или отключить эту функцию в диалоговом окне «Параметры».
- Строка, содержащая разделитель /** , не обрабатывается как комментарий, если оставшаяся ее часть представляет собой пробелы. Если первый знак после разделителя /** является пробелом, то этот пробел игнорируется, а оставшаяся часть строки обрабатывается. В противном случае весь текст, расположенный в строке после разделителя /** , обрабатывается как часть комментария.
- Строка, содержащая разделитель */ , игнорируется, если перед разделителем */ стоят только пробелы. В противном случае текст, расположенный в строке до разделителя */ , обрабатывается как часть комментария.
- В начале каждой из строк, расположенных после строки, которая начинается с разделителя /** , компилятор выполняет поиск общего шаблона. Шаблон может включать необязательный пробел и знак звездочки ( * ), после которого следуют необязательные пробелы. Если компилятор находит общий шаблон в начале каждой строки, которая не начинается с разделителя /** или не заканчивается разделителем */ , он игнорирует этот шаблон для каждой строки.
- В следующем комментарии обрабатывается только строка, которая начинается с . Формат с тремя тегами позволяет создать точно такие же комментарии.
/** text */ /** text */ /** * text */ /** * * text */ /** * text */ /** * * text * text2 * */ Для ссылки на XML-элементы (например, если функция обрабатывает определенные XML-элементы, которые требуется включить в комментарии XML-документации) можно использовать стандартный механизм заключения в скобки ( < и > ). Для ссылки на универсальные идентификаторы в элементах ссылок кода ( cref ) можно использовать escape-символы (например, cref=»List<T>» ) или фигурные скобки ( cref=»List» ). В особом случае компилятор анализирует фигурные скобки, как угловые, чтобы при ссылке на универсальные идентификаторы сделать комментарий документации менее громоздким.
Комментарии XML-документации не являются метаданными. Они не включаются в скомпилированную сборку, и поэтому не доступны посредством отражения.
Средства, принимающие входные данные XML-документации
Следующие средства создают выходные данные на основе XML-комментариев:
- DocFX: DocFX — это генератор документации API для .NET, который сейчас поддерживает C#, Visual Basic и F#. Он также позволяет изменять создаваемую справочную документацию. DocFX создает статический веб-сайт HTML на основе исходного кода и файлов Markdown. Кроме того, DocFX предоставляет гибкие возможности по настройке макета и стиля веб-сайта с помощью шаблонов. Можно также создавать пользовательские шаблоны.
- Sandcastle: средства Sandcastle создают файлы справки для библиотек управляемых классов, содержащие как концептуальные страницы справки, так и страницы справки для API. Средства Sandcastle работают из командной строки и не имеют графического интерфейса, функций управления проектами или автоматизированного процесса сборки. Средство Sandcastle Help File Builder предоставляет автономный пользовательский интерфейс и инструменты командной строки для создания файла справки в автоматическом режиме. Также доступен пакет интеграции Visual Studio, позволяющий создавать проекты справки и управлять ими только из Visual Studio.
- Doxygen: Doxygen создает интерактивный обозреватель документации (в формате HTML) или автономное справочное руководство (в формате LaTeX) на основе набора исходных файлов с комментариями документации. Также поддерживается создание документации в форматах RTF (MS Word), PostScript, PDF с гиперссылками, HTML со сжатием, DocBook и страницы руководства Unix. Doxygen можно настроить для извлечения структуры кода из исходных файлов без комментариев документации.
Строки идентификаторов
Каждый тип или член хранится в элементе в выходном XML-файле. Каждый из этих элементов имеет уникальную строку идентификатора, определяющую тип или член. Строка идентификатора должна учитывать операторы, параметры, возвращаемые значения, параметры универсального типа, а также параметры ref , in и out . Чтобы закодировать все эти потенциальные элементы, компилятор следует четко определенным правилам при создании строк идентификаторов. С помощью строки идентификатора программы, обрабатывающие XML-файл, могут определить, к какому элементу метаданных или отражения .NET применяется эта документация.
Компилятор соблюдает следующие правила при формировании строк идентификаторов.
- В строке нет пробелов.
- Первая часть строки определяет тип элемента, использующего один символ, за которым следует двоеточие. Используются следующие типы элементов.
| Знак | Тип члена | Примечания |
|---|---|---|
| Нет | namespace | Вы не можете присвоить комментарий документации пространству имен, но можете создать для него cref-ссылку, если такие ссылки поддерживаются. |
| T | type | В качестве типа может использоваться класс, интерфейс, структура, перечисление или делегат. |
| C | поле | |
| С | свойство; | Включает индексаторы или другие индексированные свойства. |
| M | method | Включает специальные методы, такие как конструкторы и операторы. |
| E | event | |
| ! | текст ошибки | Остальная часть строки предоставляет сведения об ошибке. Компилятор C# создает сведения об ошибках для ссылок, которые не могут быть разрешены. |
- Базовые типы. Обычные типы ( ELEMENT_TYPE_CLASS или ELEMENT_TYPE_VALUETYPE ) представляются в виде полного имени типа.
- Встроенные типы (например, ELEMENT_TYPE_I4 , ELEMENT_TYPE_OBJECT , ELEMENT_TYPE_STRING , ELEMENT_TYPE_TYPEDBYREF и ELEMENT_TYPE_VOID ) представляются в виде полного имени соответствующего полного типа. Например, System.Int32 или System.TypedReference .
- ELEMENT_TYPE_PTR представляется как «*» после измененного типа.
- ELEMENT_TYPE_BYREF представляется как «@» после измененного типа.
- ELEMENT_TYPE_CMOD_OPT представляется в виде «!» и полного имени класса модификатора после имени измененного типа.
- ELEMENT_TYPE_SZARRAY представляется в виде «[]» после типа элемента массива.
- ELEMENT_TYPE_ARRAY представляется как [ ELEMENT_TYPE_ARRAY : size , size : size ], где число запятых равно рангу 1, а нижние границы и размер каждого измерения, если они известны, представлены в десятичном формате. Если нижняя граница или размер не указаны, они опускаются. Если нижняя граница и размер для определенной размерности опущены, опускается и символ «:». Например, двухмерный массив со значением 1 для нижних границ без указания размеров обозначается так: «[1:,1:]».
- ELEMENT_TYPE_PINNED представляется в виде «^» после имени измененного типа. Компилятор C# никогда не создает такую кодировку.
- ELEMENT_TYPE_CMOD_REQ представляется как «|», а полное имя класса модификатора — после измененного типа. Компилятор C# никогда не создает такую кодировку.
- ELEMENT_TYPE_GENERICARRAY представляется в виде «[?]» после типа элемента массива. Компилятор C# никогда не создает такую кодировку.
- ELEMENT_TYPE_FNPTR представляется как «= FUNC: type ( ELEMENT_TYPE_FNPTR )», где type — тип возвращаемого значения, а type — это аргументы метода. Если аргументы не используются, скобки опускаются. Компилятор C# никогда не создает такую кодировку.
- Следующие компоненты сигнатуры не представляются, поскольку они никогда не используются для различения перегруженных методов:
- соглашение о вызовах;
- тип возвращаемого значения;
- ELEMENT_TYPE_SENTINEL
Примеры ниже демонстрируют, как создаются строки идентификаторов для класса и его элементов.
namespace MyNamespace < ////// Enter description here for class X. /// ID string generated is "T:MyNamespace.MyClass". /// public unsafe class MyClass < ////// Enter description here for the first constructor. /// ID string generated is "M:MyNamespace.MyClass.#ctor". /// public MyClass() < >////// Enter description here for the second constructor. /// ID string generated is "M:MyNamespace.MyClass.#ctor(System.Int32)". /// /// Describe parameter. public MyClass(int i) < >////// Enter description here for field message. /// ID string generated is "F:MyNamespace.MyClass.message". /// public string? message; ////// Enter description for constant PI. /// ID string generated is "F:MyNamespace.MyClass.PI". /// public const double PI = 3.14; ////// Enter description for method func. /// ID string generated is "M:MyNamespace.MyClass.func". /// ///Describe return value. public int func() < return 1; >////// Enter description for method someMethod. /// ID string generated is "M:MyNamespace.MyClass.someMethod(System.String,System.Int32@,System.Void*)". /// /// Describe parameter. /// Describe parameter. /// Describe parameter. ///Describe return value. public int someMethod(string str, ref int nm, void* ptr) < return 1; >////// Enter description for method anotherMethod. /// ID string generated is "M:MyNamespace.MyClass.anotherMethod(System.Int16[],System.Int32[0:,0:])". /// /// Describe parameter. /// Describe parameter. ///Describe return value. public int anotherMethod(short[] array1, int[,] array) < return 0; >////// Enter description for operator. /// ID string generated is "M:MyNamespace.MyClass.op_Addition(MyNamespace.MyClass,MyNamespace.MyClass)". /// /// Describe parameter. /// Describe parameter. ///Describe return value. public static MyClass operator +(MyClass first, MyClass second) < return first; >////// Enter description for property. /// ID string generated is "P:MyNamespace.MyClass.prop". /// public int prop < get < return 1; >set < >> ////// Enter description for event. /// ID string generated is "E:MyNamespace.MyClass.OnHappened". /// public event Del? OnHappened; ////// Enter description for index. /// ID string generated is "P:MyNamespace.MyClass.Item(System.String)". /// /// Describe parameter. /// public int this[string s] < get < return 1; >> ////// Enter description for class Nested. /// ID string generated is "T:MyNamespace.MyClass.Nested". /// public class Nested < >////// Enter description for delegate. /// ID string generated is "T:MyNamespace.MyClass.Del". /// /// Describe parameter. public delegate void Del(int i); ////// Enter description for operator. /// ID string generated is "M:MyNamespace.MyClass.op_Explicit(MyNamespace.MyClass)~System.Int32". /// /// Describe parameter. ///Describe return value. public static explicit operator int(MyClass myParameter) < return 1; >> >Спецификация языка C#
Дополнительные сведения см. в приложении Спецификация языка C# в комментариях документации.