Комментарии в XML-файле, как это сделать
Обновлено: 26.06.2024
В Dynamics 365 Business Central вы можете добавлять документацию к своему коду, включая элементы XML в специальные поля комментариев непосредственно в исходном коде перед блоком кода, к которому относится комментарий. Комментарий к документации должен непосредственно предшествовать определяемому пользователем типу, который он аннотирует, например кодовому блоку, таблице или интерфейсу, или члену, такому как поле или метод. Синтаксис добавления XML-комментариев в ваш код — это тройная косая черта ///, за которой следует один из поддерживаемых тегов XML. Существует поддержка IntelliSense для написания комментариев к документации. Наиболее важно предоставить комментарий к документации шаблона при написании третьей косой черты в тройной косой черте.
Комментарии к документации видны при наведении курсора на исходные символы, в списках завершения и в справке по подписи. Добавляя XML-комментарии в код, вы можете улучшить его читаемость, добавить полезную информацию о реализации и помочь другим использовать написанный вами код. С комментариями XML вы также включаете IntelliSense в коде Visual Studio для объектов AL, которые вы добавляете в свой код в качестве помощи другим разработчикам, работающим с вашим кодом или расширяющим его. Это означает, что когда вы создаете расширение, а кто-то расширяет этот код, они получат встроенную документацию при вызове данного объекта.
Интеграция с инструментами генерации документации, такими как DocFx и SandCastle, в настоящее время не поддерживается.
Если для параметра allowDownloadingSource в файле app.json задано значение false, а затем вы загружаете пакет приложения; пакет приложения не будет содержать XML-комментариев.
Поддерживаемые теги XML
В следующей таблице перечислены элементы XML, которые поддерживаются для AL.
Синтаксис списка
Пример
Следующий пример взят из файла Email.Codeunit.al в системном приложении. В этом примере параметр EmailMessageId задокументирован с помощью тега
Специальные символы
Чтобы специальные символы, такие как угловые скобки, появлялись в тексте комментария к документации, используйте HTML-кодировку и >, которая равна < и > соответственно. В следующем примере показано, как это сделать.
Советы по написанию
Комментарии к коду улучшают читабельность разработанного вами кода и очень полезны для тех, кто модифицирует или поддерживает этот код. Кроме того, комментарии к коду составляют основу автоматически создаваемой документации. Хорошие комментарии к коду должны делать следующее:
Т.е. Как я могу закомментировать и все, что внутри, в приведенном ниже коде?
Я мог бы использовать, но это только для одиночных тегов (как я знаю), таких как // в Java и C. Я хотел бы что-то более похожее на то, как /** комментарий **/ можно использовать в Java и C, поэтому Я могу комментировать более длинные блоки XML-кода.
Вы должны знать, что комментарии в XML-файле считаются узлами типа XmlComment. Поэтому, если вы загрузите файл xml, эти узлы комментариев будут загружены, и вам решать, избегать их или фильтровать их при анализе загруженного содержимого.
9 ответов 9
Вы можете использовать этот стиль комментария в нескольких строках (который также существует в HTML)
Одно предостережение заключается в том, что у вас могут возникнуть проблемы с вложенными комментариями. Вам нужно будет либо: (1) удалить завершающий ">" в конце вложенного комментария, либо (2) полностью удалить вложенные комментарии.
У меня возникли проблемы с (1), так как у некоторых программ чтения XML (например, CruiseControl.NET) могут возникнуть проблемы с чтением вложенного комментария, в конце которого удален символ ">". В итоге мне пришлось полностью удалить комментарии.
@coderob На самом деле даже -- нельзя использовать в XML-комментариях. Поэтому вам, возможно, придется удалить весь -->
Можно столкнуться с проблемами, используя -- в этом типе комментариев. Лучше использовать ---> если вам нужно временно вложить комментарий. Во всяком случае, в HTML (подмножество xml), включая -- внутри комментария, это недействительно. Обычно вам это сойдет с рук, но иногда это вызывает проблемы. Итак, я обязательно избегаю множественных - в строке в комментариях, и если мне нужно временно вложить комментарий, я поставлю пробелы между двумя закрывающими -- в --> . Это позволяет избежать случайных нечетных ошибок в XML и HTML.
Вы можете обернуть текст несуществующей инструкцией по обработке, например:
Этот метод работал именно так, как мне было нужно, и имел дополнительное преимущество, заключающееся в том, что он работал даже с внутренними комментариями. Я бы использовал это вместо принятого ответа, если у вас есть какая-либо форма сложного кода.
Это работает даже с искаженным XML внутри. Так что это отличное решение для временного комментирования блока.
Если вы спросите, потому что вы получили ошибки с синтаксисом, скорее всего, это раздел CDATA (и там часть ]]>), который затем находится в середине комментария.Это не должно иметь значения, но иногда идеальный и реальный мир могут немного отличаться друг от друга (особенно когда речь идет об обработке XML).
Попробуйте также изменить ]]> :
Это довольно распространенная ошибка. Он унаследован от того, как SGML обрабатывает комментарии. (Прочитайте спецификацию XML в этой теме)
Большое спасибо за упоминание странного факта с двойным дефисом --! У меня был случай, когда я закомментировал комментарий. Хотя я удалил старое окончание комментария, это не удалось. Пример: . -->
Вас не смущает термин «XML-комментарии»? Ну, будьте уверены. Ты не один. «Это относится к комментариям внутри XML-файла?» Вы можете задаться вопросом. Или, может быть, у вас есть смутное представление о том, что это как-то связано с какой-то документацией по программированию исходного кода. Оба предположения в чем-то верны. Но вы все еще читаете этот пост, а это значит, что это «вроде» вас не урежет, верно?
Итак, этот пост посвящен XML-комментариям. Вы узнаете, что на самом деле означает этот термин, для чего нужны (и не годятся) комментарии XML, а также узнаете кое-что о документации программного обеспечения. Если вы готовы, то давайте начнем!
Комментарии XML: определение снизу вверх
Если выражение «XML-комментарии» вам ничего не говорит, одной из возможных причин может быть то, что вы не знакомы с отдельными терминами «XML» и «комментарии». Итак, мы начнем с устранения этого источника путаницы, разбивки термина и определения каждого слова по отдельности. Да, мы предполагаем, что в этом разделе вы находитесь на начальном уровне, поэтому можете пропустить его, если вы знакомы с определениями как XML, так и комментариев.
Кажется, я впервые услышал об XML, когда кто-то сказал мне, что это «что-то вроде HTML, но вы создаете свои собственные теги». Хотя это и так, нам определенно нужно больше для определения.
Для начала XML означает «расширяемый язык разметки». Как и HTML, XML является языком разметки. Он использует специальные метки, называемые «тегами», для аннотирования частей текста, чтобы придать ему особое значение или другие атрибуты. В отличие от HTML, XML не имеет фиксированного набора доступных тегов. Вместо этого вы создаете теги, необходимые для представления документа или структуры данных, которые вы хотите закодировать. Пока XML правильно сформирован, все готово.
Комментарии
Комментарии в нашем контексте относятся к комментариям на языке программирования. И что это? Короче говоря, комментарии — это фрагменты текста, которые вы включаете в свой исходный код, но на самом деле они не являются инструкциями по программированию. Они игнорируются компилятором или интерпретатором. Их единственная цель — предоставить некоторую информацию будущим читателям вашего кода.
Подведение итогов
Теперь у нас есть и «XML», и «комментарии». Итак, как мы можем объединить два слова таким образом, чтобы это имело смысл? На мой взгляд, «комментарии XML» могут означать только две возможные вещи:
- Комментарии внутри документа XML;
- Комментарии на языке программирования, который так или иначе использует формат XML.
Теперь мы рассмотрим каждую из перечисленных выше возможностей.
XML-комментарии, как в разделе «Комментарии внутри XML-документа»
Допустим, у вас есть следующий XML-документ:
Представьте, что вам нужно вставить сообщение между вторым и третьим элементами, чтобы предоставить пользователю дополнительную информацию. Вот как вы это сделаете, используя однострочный комментарий.
Что бы вы сделали, чтобы интерпретатор XML проигнорировал отрывок из документа? Этот ответ также заключается в использовании стиля многострочных комментариев.
Обратите внимание, что, несмотря на то, что мы использовали комментарии для игнорирования двух элементов в нашем XML-документе, результирующий текст по-прежнему является допустимым, правильно сформированным XML-документом. Например, следующий документ будет считаться недействительным:
В приведенном выше примере у нас есть закрывающий тег без соответствующего открывающего, что делает документ некорректным.
Правила комментариев XML
Теперь мы рассмотрим правила, которым необходимо следовать при работе с XML-комментариями. Их всего четверо.
Нельзя помещать комментарий перед объявлением XML
Во-первых, вы не можете разместить комментарий перед объявлением XML. Объявление XML обычно является первым в XML-файле. Несмотря на то, что объявление XML не требуется в версии XML 1.0, когда вы включаете его, оно должно быть первым, что появляется в файле.
Смысл этого правила в том, что вы не можете размещать комментарий перед объявлением XML.
Нельзя помещать комментарий в значения атрибутов
Как и первое, второе правило также является ограничением. В нем говорится, что вам не разрешено размещать комментарий в значении атрибута. Таким образом, следующая выдержка из XML будет недействительной:
Комментарии нельзя вкладывать в другие комментарии
Это довольно очевидно: вложенные XML-комментарии не допускаются.
За исключением мест, указанных в приведенных выше правилах, комментарии могут появляться в любом месте XML-документа
Последнее правило является логическим следствием предыдущих. То есть, пока вы не пытаетесь поместить комментарий перед объявлением XML, внутри значения атрибута или внутри другого комментария, все будет в порядке.
Комментарии XML как в «Документации API в формате XML»
Документация по API — очень ценный инструмент для любой команды разработчиков. Да, чистый, лаконичный и не требующий пояснений код может иметь большое значение, но часто требуется специальная документация. И это особенно верно для кода, который используется сторонними организациями, такими как библиотеки и фреймворки. Некоторые языки/платформы разрабатывают свои собственные форматы документации по API. Так обстоит дело, например, с Java и Javadoc.
Легко. Открыв Visual Studio, поместите курсор над любым членом, нажмите клавишу косой черты три раза, и Visual Studio автоматически создаст шаблон для заполнения. Допустим, у вас есть следующий метод:
После размещения курсора над методом «Добавить» и нажатия клавиши косой черты три раза подряд, VS сгенерирует для вас следующее:
С этого момента вам нужно будет просто заполнить шаблон. Сначала вы вводите общее описание метода, а затем документацию по двум параметрам. Наконец, вы должны задокументировать возвращаемое значение.
Быстрый пример
Предположим, мы пишем приложение для управления учебным заведением, и теперь нам нужно создать метод поиска для класса StudentRepository.
Как видите, приведенный выше код содержит метод, который ищет учащихся по их фамилиям. Для краткости я опустил часть метода, которая действительно что-то делала. Однако для целей нашего примера это не имеет значения. Что касается документации участников, важной частью является общедоступный интерфейс, а не внутренняя реализация. Продолжим.
Начнем с заглушки документации
Теперь мы собираемся использовать теги XML-документации для создания документации по коду для метода из приведенного выше примера. Поместите курсор над методом и нажмите клавишу косой черты 3 раза подряд, и Visual Studio поместит следующую документацию над методом:
Теперь давайте объясним каждый из тегов, которые вы видите в приведенном выше примере.
Тег
Тег позволяет дать краткое описание того, что делает этот участник. Вы должны написать резюме, которое должно быть как можно более описательным и ясным, и оставаться в простом настоящем времени.
тег позволяет сообщить не только описание параметра, но и его имя через атрибут «имя».
Экземпляр System.String, представляющий ISBN книги для поиска.
Тег
Тег предназначен для описания возвращаемого значения вашего метода. Помимо описания того, что должно быть возвращено, когда все идет хорошо, также полезно описать, что происходит в «печальных» сценариях пути. Например, предположим, что если метод не может найти ни одного студента с определенной фамилией, он возвращает пустой IEnumerable. Вы обязательно должны включить такую информацию в текст тега.
Полный пример
Посмотрите на готовый пример со всеми заполненными тегами:
Завершенный пример содержит несколько дополнительных тегов. Кроме того, мы могли бы добавить больше тегов. Есть тег, который имело смысл добавить, так как метод в примере вызывает некоторые сценарии. Но мы не будем рассматривать ни один из них, поскольку у нас уже есть публикации, в которых теги XML-документации рассматриваются более подробно.
С этим покончено, давайте продолжим. В чем причина использования XML-комментариев любого типа? Это то, что вы увидите в следующем разделе.
XML-комментарии: для чего они нужны?
Теперь вы знаете о двух типах XML-комментариев, но, возможно, вам все еще интересно, есть ли какая-либо ценность в любом из них. Для первого типа комментариев ценностное предложение очевидно.Комментирование одной или нескольких строк документа позволяет разработчику быстро отключить некоторые строки, чтобы проверить или отладить гипотезу.
Что касается второй категории, я бы сказал, что ценностное предложение еще яснее. Документация по программному обеспечению обязательна, независимо от размера компании, опыта команды или любого другого фактора. Начните документировать свои API как можно скорее!
Назад к вам
В этом посте мы познакомили вас с определением несколько запутанного термина. Мы разбили его на составные части, определив каждую по отдельности, прежде чем снова собрать их вместе. Затем мы продолжили объяснять, что может означать этот термин, показывая примеры использования в обоих значениях.
Несмотря на то, что в этой публикации не предлагалось каноническое определение «XML-комментариев», я надеюсь, что нам удалось пролить свет на эту тему. Надеемся, что теперь вы хотя бы немного лучше понимаете документацию программного обеспечения и чувствуете вдохновение немедленно приступить к документированию своих программных артефактов.
Спасибо, что прочитали. Увидимся в следующий раз!
Узнайте, как GhostDoc может помочь упростить ваши XML-комментарии, создавать и поддерживать качественную справочную документацию, создавать документацию IntelliSense.
Комментарии XML могут быть разделены на две части. Во-первых, XML, как и HTML, является языком разметки, и вы можете создавать собственные теги и комментарии на языке программирования, они представляют собой небольшой фрагмент текста, формулы или что-то еще. выражения, включенные в исходный код XML, содержащие инструкции по программированию в каждой строке, и могут быть добавлены в любое место в коде XML, что помогает разработчику понять существующий код для будущего анализа. Комментарии полностью игнорируются компилятором и помогают пользователям в будущем при чтении кода. Таким образом, XML-комментарии — это отдельный символ или набор абзацев, которые помимо кода предоставляют формальную документацию и помогают понять общие теги, используемые в XML-файле. Это помогает включать примечания или любые наблюдения в файл XML.
Типы комментариев XML
Комментарии в XML объявляются как:
Веб-разработка, языки программирования, тестирование программного обеспечения и другое
Он состоит из двух разделов, начинающихся и заканчивающихся комментарием. Должно быть очень ясно, что вложенные комментарии не выполняются. вот синтаксис.
Примечание: нельзя ставить тире в середине комментариев. Обе стороны включают два тире. Комментарий XML поддерживает все теги HTML для добавления дополнительных вариантов использования.
Форма древовидной структуры задается как:
Комментарий:
Недопустимое представление Xml Comment показано ниже:
// Не допускается последовательность символов.
// недопустимый конец дефиса
// нельзя вкладывать
XML-комментарии и примеры
Комментарии XML можно классифицировать и использовать следующими способами.
1. Комментарии внутри документа XML
Это обычный тип, когда комментарий размещается вверху. Необходимость комментария потенциально делает код понятным, а всякий раз, когда код документа обновляется через год или месяц, также требуется обновить комментарий.
Обучение XML (5 курсов, 6+ проектов) 5 онлайн-курсов | 6 ручных проектов | 40+ часов | Поддающийся проверке сертификат об окончании | Пожизненный доступ
4,5 (8522 оценки)
Давайте рассмотрим несколько примеров, чтобы получить четкое представление по теме. Он вставляется в начало кода. В приведенном ниже примере дается однострочный комментарий перед корневым элементом. Этот комментарий обеспечивает удобочитаемость всего документа для понимания назначения тегов.
Код:
Dhaba Special
ECR-II
Шведский стол 100
День рождения
A
Beach Resort
Брюс
94 минуты -Официант
Средняя вечеринка
B
Вывод:
Код:
Вывод:
2. Комментарии, используемые в схеме xsd
Его можно использовать в любом месте внутри элемента. С четким объяснением может быть включен между любым дочерним элементом компонента XSD. Комментарии внутри элементов схемы объявляются следующими способами:
Комментарий:
Код:
Вывод:
Соответствующий результат файла xml (используйте конвертер xsd в xml, чтобы увидеть вывод)
Код:
Это страница, на которой лучший ресторан появляется наверху
Это название ресторана, который взял на себя
Это предназначено для подачи блюд для клиентов
Площадь может быть отведена под вечеринку
Это оценка пользователей
-->
Dhaba Special
ECR-II
Шведский стол 100
День рождения
А
Пляжный курорт
Брюс
94 минуты -Официант
Средний-вечеринка
Б
Вывод:
Здесь второй элемент не выполняется процессором, так как он объявлен как комментарий xml. Здесь во время проверки синтаксический анализатор анализирует первый элемент, а не второй дочерний элемент.
Код:
Дэниел Круз
Наука
Навин Радж
Математика
Вывод:
3. Языки программирования используют формат XML
подразумевает значение для методов и определяет значение.
Код:
используя Систему;
класс calv
///
/// проверить значение и обновить его.
///
///
Заданное значение.
/// Измененное значение.
static int check(int x)
return x * 3;
>
static void Main()
Console.WriteLine(check(9));
>
>
Вывод:
Правила комментариев XML
Ниже показаны некоторые правила, которые необходимо учитывать при работе с XML-комментариями.
- Комментарии XML не разрешается размещать перед объявлением XML, поскольку оно появляется первым в коде. Добавление справочных комментариев не должно противоречить объявлению XML.
- Второе правило заключается в том, что комментарии нельзя размещать между элементами атрибута. Весь текст должен быть заключен между символами меньше и больше.
- Вложенные комментарии не допускаются. Ссылки на сущности не распознаются в строке комментария.
Заключение
Поэтому в заключение эта статья посвящена XML-комментариям, и мы узнали, что это за термин и для чего используются XML-комментарии. Затем мы перешли к тому, что означает этот термин, а также к простым примерам. Хотя это не дает ясного комментария, по крайней мере, мы немного прояснили эту тему. Наконец, эти комментарии помогают предоставить простой контекст для XML-кода, который помогает другим удаленным разработчикам понять код во время связи между клиентом и сервером.
Рекомендуемые статьи
Это руководство по XML-комментариям. Здесь мы обсуждаем введение в XML-комментарии и его типы вместе с примерами и реализацией кода. Вы также можете просмотреть другие предлагаемые нами статьи, чтобы узнать больше –
Читайте также: