Строка Xml в сводном комментарии С#

Я документирую несколько методов, которые я написал в С#, которые касаются разбора токенов. Из-за некоторых технических ограничений в других областях системы эти токены должны принимать форму элементов XML (т.е. <tokenName />). Я хотел бы указать формат этих токенов в самом сводном отчете.

Однако это порождает ошибку: плохо сформированный XML - имя было запущено с недопустимым символом ". Есть ли какая-либо escape-последовательность символов, которую я могу использовать для вставки XML в сводные комментарии С#?

Ответ 1

Использовать стандартное экранирование XML. Например:

<summary>This takes a &lt;token1&gt; and turns it into a &lt;token2&gt;</summary>

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

Ответ 2

Используйте раздел CDATA. Например:

<![CDATA[ <name>Bob</name> ]]>

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

Если XML, который вы хотите встроить, содержит разделы CDATA, вам нужно использовать несколько разделов CDATA, как описано в другом ответе на переполнение стека или на Wikipedia. Или вы всегда можете использовать ссылки на простые сущности, как описано в других ответах здесь.

Ответ 3

Я использую escape-последовательности, потому что всплывающая подсказка VisualStudios не отображает ничего внутри секции CDATA.

Ответ 4

Очень поздно, но столкнулся с той же проблемой, используя <![CDATA[]]> скроет комментарий в Intellisense.

Замена обоих < и > была для меня очень полезной (ленивой:)). Я узнал, что просто заменить < на < было достаточно для Intellisense, потому что это делает xml недействительным и подходит для анализа Intellisense как текст в сводном блоке.

Вот пример:

/// <summary>
/// Parse the queue process response
/// <para>&lt;?xml version="1.0" encoding="utf-16"?>&lt;result success="True">&lt;entity type="resource" operation="update" />&lt;/result></para>
/// <![CDATA[
/// <?xml version="1.0" encoding="utf-16"?><result success="True"><entity type="resource" operation="update" /></result>
/// ]]></summary>
/// <param name="response"></param>
/// <returns></returns>

Intellisense покажет это:

Parse the queue process response
<?xml version="1.0" encoding="utf-16"?><result success="True"><entity type="resource" operation="update" /></result>