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

Обновлено: 05.07.2024

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

Я мог бы использовать , но только для одиночных тегов (как я знаю), таких как // в Java и C. Мне хотелось бы, чтобы что-то больше понравилось, как /** comment **/ можно использовать в Java и C, поэтому Я могу прокомментировать более длинные блоки XML-кода.

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

Вы можете использовать этот стиль комментария для нескольких строк (который существует и в HTML)

Единственное предостережение в том, что у вас будут проблемы с вложенными комментариями. Вам нужно будет либо: (1) удалить завершающий символ ">" на закрытии вложенного комментария, либо (2) удалить вложенные комментарии вообще.

У меня возникли проблемы с (1), поскольку у некоторых программ чтения XML (например, CruiseControl.NET) могут возникнуть проблемы с чтением вложенного комментария, в конце которого ">" удалено. В итоге мне пришлось полностью удалить комментарии.

@coderob На самом деле, даже - не допускается в комментариях XML. Так что, возможно, вам придется удалить весь ->

В Android Studio выберите блок, затем Ctrl + Slash, чтобы прокомментировать его (или Ctrl + Shift + Slash).

Можно столкнуться с проблемами, используя -- в этом типе комментария. Лучше использовать - -> если вам нужно временно вставить комментарий. В любом случае в HTML (подмножество xml), в том числе -- внутри комментария недопустимо. Обычно с этим можно сойти, но иногда это вызывает проблемы. Итак, я обязательно буду избегать нескольких - подряд в комментариях, и если мне понадобится временно вставить комментарий, я буду ставить пробелы между 2 закрывающими -- из --> . Это позволяет избежать случайных нечетных ошибок в XML и HTML.

Если вы спросите, потому что вы получили ошибки с синтаксисом , это, скорее всего, раздел CDATA (и там часть ]]> ), который затем лежит в середине комментария. Это не должно меняться, но идеальный и реальный мир может быть немного раздельным, иногда (особенно когда дело касается обработки XML).

Попробуйте также изменить ]]> :

Другое дело, что приходит на ум: если содержимое вашего XML где-то содержит два дефиса, комментарий сразу же заканчивается на нем:

Это довольно распространенная ошибка. Он унаследовал от того, как SGML обрабатывает комментарии. (Прочитайте спецификацию XML в этом разделе)

Большое спасибо за упоминание странного факта с двойными дефисами! У меня был случай, когда я закомментировал комментарий. Хотя я удалил конец старого комментария, это не удалось. Пример: . ->

Вы можете обернуть текст несуществующей инструкцией по обработке, например:

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

Это даже работает с искаженным XML внутри. Так что это отличное решение для временного комментирования блока.

Собственно, вы можете использовать формат с несколькими строками или тегами:

Здесь для комментариев мы должны писать, как показано ниже:

Ярлык для комментария одной строки:

Ярлык для комментариев нескольких строк:

Одна вещь, которую вы должны иметь в виду, вы не можете прокомментировать атрибут XML-тега. Например:

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

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

А теперь мы рассмотрим теги, рекомендованные для использования. Для того, чтобы начать их вводить, нужно сначала поставить "///".

///
/// Этот метод передаёт привет ХабраХабру столько раз, сколько скажите.
///
///
Сколько раз передать привет

/// Сама строка с приветами
public string HelloHabr( int repeat)
string result = "" ;
for ( int i = 0; i "Hello, HabraHabr!\n" ;
>
return result;
>

А вот так наш метод будет показан в IntelliSense:

Подробно про все можно почитать как всегда на MSDN.

Ну вот, для начала наверно все. Начинайте пока правильно документировать свой код, а я подготовлю еще пару статей на эту тему, если эта окажется актуальной.

Использование XML комментариев

Создание документированного компонента

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

1. Создание компонента
2. Создание XML файла
3. Тестирование компонента в сценарии развертывания

Шаг 1, создание компонента

Поначалу название этого шага может звучать пугающе, примерно как указание "снимите крышу, отложите" в качестве шага 1 в плане реконструкции вашего дома. Однако процесс создания компонента хорошо описан в нескольких разборах программ, приведенных в MSDN Library & VS documentation; поэтому мы не будем на этом останавливаться, а возьмем простой пример и используем его, чтобы показать, как добавить XML документацию.

Окончательной целью этого пошагового руководства является создание двух файлов. Первый - .DLL, которую будет использовать потребитель компонента; второй - .XML файл, содержащий всю документацию для этого компонента. Структура компонента-образца следующая:

namespace XMLDeploy1
public class Temperature
public static int CelsiusToFahrenheit(int degreesCelsius)
return ((int)((9/5)*degreesCelsius) + 32);
>

public static int FahrenheitToCelsius(int degressFahrenheit)
return ((int)((5/9)*(degressFahrenheit - 32)));
>
>
>

Обратите внимание, что в компоненте пропущена очень важная часть - документация! Несмотря на сравнительную простоту компонента, в нем есть три момента, где добавленная документация будет чрезвычайно полезна для потребителя компонента. Эти три момента - это документация уровня класса, документация уровня метода и документация уровня параметра.

Чтобы добавить документацию уровня класса, наберите /// в строке над

Затем между автоматически сгенерированными тегами опишите то, для чего предназначен класс Temperature. Например:

///
/// Класс temperature предоставляет функции для преобразования
/// показаний различных шкал температур.
///
public class Temperature

Документация уровня метода и параметра примыкает к данному методу, так же как только что добавленная нами документация примыкала к классу. Например, давайте добавим комментарии к методу

Наберите /// перед описанием метода, обратите внимание, что при этом были автоматически сгенерированы и добавлены в исходный код три тега. Первый, , удобен для описания того, что делает метод. Второй, , используется для описания того, что необходимо передать в 'degreesCelsius'. И третий тег, , подходит для описания возвращаемого значения метода. Документированный метод выглядит примерно так:

///
/// Преобразовывает градусы Цельсия в градусы по Фаренгейту
///
/// Degrees Celsius
/// Возвращает градусы по Фаренгейту
public static int CelsiusToFahrenheit(int degreesCelsius)

После применения этих же шагов для создания документации уровня метода и параметра ко второму методу класса, наш пример выглядит так:

namespace XMLDeploy1
///
/// Класс temperature предоставляет функции для преобразования
/// показаний различных шкал температур.
///
public class Temperature
///
/// Преобразовывает градусы Цельсия в градусы по Фаренгейту
///
/// Degrees Celsius
/// Возвращает градусы по Фаренгейту
public static int CelsiusToFahrenheit(int degreesCelsius)
return ((int)((9/5)*degreesCelsius) + 32);
>

///
/// Преобразовывает градусы по Фаренгейту в градусы Цельсия
///
/// Degrees Fahrenheit
/// Возвращает градусы Цельсия
public static int FahrenheitToCelsius(int degressFahrenheit)
return ((int)((5/9)*(degressFahrenheit - 32)));
>
>
>

Шаг 2, создание XML файла

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

Чтобы создать XML файл, откройте "Solution Explorer", щелкните правой кнопкой проект и выберите "Properties". В открывшемся диалоговом окне выберите "Build" в папке "Configuration Properties".

Рисунок 1. Solution Explorer

Обратите внимание на свойство "XML Documentation File". Введите имя .XML файла, который должен быть сгенерирован.

Комментарий: это имя должно быть таким же, т.к. .DLL или IntelliSense не смогут найти его.

Шаг 3, тестирование компонента в сценарии развертывания

Создайте новый проект, чтобы протестировать только что созданный компонент с включенными XML комментариями. После создания проекта, щелкнув правой кнопкой проект в solution explorer и выбрав 'add reference' в контекстном меню, откройте диалоговое окно 'add references'. Щелкните кнопку 'browse' и найдите .DLL компонента, который мы только что создали. Выберите этот файл и щелкните ok. Этим вы добавите в тестовом проекте ссылку на компонент, созданный в шаге 1. При добавлении ссылки в директорию "bin" тестового приложения копируются .DLL и .XML файл (.XML файл и .DLL должны находится в одной директории, или будет скопирован только .DLL). Теперь IntelliSense будет разбирать XML файл и предоставлять потребителю всплывающие подсказки.

Рисунок 2. Всплывающие подсказки.

Также VS ObjectBrowser сможет теперь видеть компонент и ассоциированную с ним документацию:

Рисунок 3. Инспектор объектов.

Этот тег обеспечивает механизм индикации того, что шрифт фрагмента текста описания должен быть таким же, какой используется в блоке кода. (Для строк кода используйте )

Синтаксис: текст который будет отформатирован так же как и код

Тег:
Этот тег используется, чтобы применить определенный шрифт к одной или более строкам исходного кода или выходных данных программы. (Для маленьких фрагментов кода в комментариях используйте .)

Синтаксис: исходный код или программный вывод

/// Этот метод изменяет положение точки
/// на x- и y-смещения.
/// Например:
///
/// Point p = new Point(3,5);
/// p.Translate(-1,3);
///
/// результат в p будем иметь значения (2,8).
///
///
public void Translate(int xor, int yor)
X += xor;
Y += yor;
>

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

Синтаксис: описание

Пример:
Пример смотрите .

Тег:
Этот тег обеспечивает возможность документировать исключительные ситуации, которые может формировать метод.

Синтаксис: description

cref="member" - Имя члена. Генератор документации проверяет существование данного члена и преобразовывает член в имя канонического элемента в файле документации.

description - Описание обстоятельств, в которых формируется исключительная ситуация.

public class DataBaseOperations
///
///
///
///
public static void ReadRecord(int flag)
if (flag == 1)
throw new MasterFileFormatCorruptException();
else if (flag == 2)
throw new MasterFileLockedOpenException();
// .
>
>

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

Синтаксис: term
description

term - Определяемый термин.
description - Описание термина.
Или элемент в маркированном списке, или нумерованный список, или определение термина.

Тег:
Этот тег предназначен для использования в других тегах, таких как или , и разрешает добавление структуры в текст.

Синтаксис: content

content - Текст абзаца.

/// This is the entry point of the Point class
/// testing program.
/// This program tests each method and operator,
/// and is intended to be run after any non-trvial
/// maintenance has been performed on the Point
/// class.
public static void Main()
// .
>

Тег:
Этот тег используется для описания параметра метода, конструктора или индексатора.

Синтаксис: description

name - Имя параметра.
description - Описание параметра.

/// This method changes the point's location to
/// the given coordinates.
/// xor is the new x-coordinate.
/// yor is the new y-coordinate.
public void Move(int xor, int yor)
X = xor;
Y = yor;
>

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

Синтаксис: name - Имя параметра.

/// This constructor initializes the new Point to
/// (,
/// ).
/// xor is the new Point's x-
/// coordinate.
/// yor is the new Point's y-
/// coordinate.
public Point(int xor, int yor)
X = xor;
Y = yor;
>

Тег:
Этот тег разрешает документирование возможности безопасного доступа к члену.

Синтаксис: description

cref="member" - Имя члена. Генератор документации проверяет существование данного элемента кода и преобразовывает член в имя канонического элемента в файле документации.
description - Описание доступа к члену.
Пример:

Тег:
Этот тег используется для включения обзорной информации о типе. (Для описания типа членов используйте .)

Синтаксис: description

description - Текст комментариев.

Тег:
Этот тег используется для описания возвращаемого методом значения.

Синтаксис: description

description - Описание возвращаемого значения.

/// Report a point's location as a string.
/// A string representing a point's location, in the form
/// (x,y), without any leading, training, or embedded
/// whitespace.
public override string ToString()
return "(" + X + "," + Y + ")";
>

Тег:
Этот тег обеспечивает возможность задавать связь в тексте. (Для обозначения текста, который должен появиться в секции See Also, используйте .)

cref="member" - Имя члена. Генератор документации проверяет существование данного элемента кода и передает член в имя элемента в файле документации.

/// This method changes the point's location to
/// the given coordinates.
///
public void Move(int xor, int yor)
X = xor;
Y = yor;
>
/// This method changes the point's location by
/// the given x- and y-offsets.
///
///
public void Translate(int xor, int yor)
X += xor;
Y += yor;
>

Тег:
Этот тег обеспечивает возможность генерировать элемент для секции See Also. (Используйте для задания связи из текста.)

Является/П'Т есть строка-комментарий в XML? Так, один, без ближе, как-то "//" и компилятор использует.

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

Нет, нет никакого способа, чтобы комментировать строки в XML и в конце комментария автоматически на перевод строки.

XML имеет только одно определение на комментарий]1:

XML-код запрещает -- в комментариях для поддержания совместимость с SGML.

Как другие сказали, нет никакого способа, чтобы сделать однострочный комментарий легально в формате XML, комментарии из нескольких строк, но, есть способы, чтобы сделать комментирование сегменты проще в XML. Глядя на пример ниже, если вы добавите '>' на линии один, XmlTag будет раскомментирован. Удалить '>' и это'ы закомментирован снова. Это самый простой способ, что я'вэ видел, чтобы быстро закомментировать/раскомментировать XML без ломания.

Если вы заботитесь о совместимости с SGML, просто используйте этот код:

Добавить '->' наверх комментарии и '-' на дне комментария. Обратная сторона медали заключается в необходимости изменить нижнюю комментарий каждый раз, который, вероятно, сделать это легче всего введите в в верхней и `--> внизу каждый раз.

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

Как закомментировать раздел XML, в котором есть комментарии?

Следующее не сработает. Это только комментирует stuff0 :

ОТВЕТЫ

Ответ 1

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

Дает следующий вывод:

Но процессор XSLT также может выдавать ошибку. Учитывая спецификацию, это до реализации, чтобы добавить пробел или вызвать ошибку.

Ответ 2

Нет. XML в соответствии со спецификацией не поддерживает вложенные комментарии.

Ответ 3

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

Сказав, что. мне действительно нужно это плохо, так вот на хитрость. Окружите раздел, который вы хотите прокомментировать, неиспользованной инструкцией обработки:

Вы можете использовать любую инструкцию по обработке, которая не используется. Я выбрал "комментарий" в качестве неиспользуемой инструкции по обработке, поэтому я начал большой комментарий с и закончил его с ?> .

Практически любое слово будет использоваться в качестве инструкции по обработке, поскольку в большинстве случаев оно не используется. Я имею в виду, вы когда-нибудь использовали?

Ответ 4

У вас есть два варианта:

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

Ответ 5

Здесь другой подход: вы могли бы просто использовать вложенные комментарии, как если бы они поддерживались в XML:

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

Читайте также: