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

StackOverflow https://stackoverflow.com/questions/607094

  •  03-07-2019
  •  | 
  •  

Вопрос

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

Однако это вызывает ошибку:Неверный формат XML — имя началось с недопустимого символа».Есть ли какая-либо последовательность escape-символов, которую я могу использовать для встраивания XML в сводные комментарии C#?

Это было полезно?

Решение

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

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

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

Другие советы

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

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

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

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

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

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

Замена обоих < и > мне пришлось много работать (ленивый :)).Я обнаружил, что просто заменив < с &lt; этого было достаточно для 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>
Лицензировано под: CC-BY-SA с атрибуция
Не связан с StackOverflow
scroll top