Как правильно экранировать содержимое примера «кода» в документации Xml?

Как избежать недопустимых символов VB и C-Sharp, таких как <>&, в теге <code> документации .Net Xml?

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

''' ------------------------------------------------------------------------
''' <summary>
''' </summary>
''' ------------------------------------------------------------------------
''' <example> This is a code example.
''' <code>
''' 
''' Dim currentPosition As Long = CLng(player.Position.TotalMilliseconds)
''' 
''' If Not ((currentPosition + 5000) >= player.Length) Then
'''    player.Seek(currentPosition + 5000)
''' End If
''' 
''' </code>
''' </example>
''' ------------------------------------------------------------------------
Sub Something
End Sub

Тогда как мне избежать содержимого кода?

У меня есть сомнения, потому что содержимое тега <code> обрабатывается как обычный текст, тогда, если я добавлю тег CDATA, чтобы избежать ошибки IntelliSense, что произойдет, когда я сгенерирую файл Chm/Html с этой документацией? Я имею в виду CDATA символы разметки будут представлены в виде литрового текста в примере кода, вызывающем невязки таким образом, что ли?.

Кто-нибудь может привести пример, чтобы сделать все правильно?


person ElektroStudios    schedule 29.10.2015    source источник
comment
Вы пробовали использовать вместо ›? Коды XML для ‹, › и &: , , .   -  person Martin Soles    schedule 29.10.2015
comment
@Martin Soles Спасибо за комментарий. Это сработало как для IntelliSense, так и для создания файла справки CHM. Не стесняйтесь опубликовать ответ, чтобы отметить его как принятый!.   -  person ElektroStudios    schedule 29.10.2015


Ответы (1)


Вам нужно использовать тот же тип экранирования, что и в обычном документе XML (или HTML) (дополнительную информацию см. здесь).

Замените & на &amp;, < на &lt;, > на &gt;. Еще один, на который вы, возможно, захотите обратить внимание, — это символ кавычек. " заменяется на &quot;.

person Martin Soles    schedule 29.10.2015
comment
Фу. Хотя это кажется решением, на самом деле сам блок документации становится гораздо менее читаемым при просмотре исходного кода, а не при просмотре всплывающей подсказки IntelliSense. Рассмотрите возможность использования дженериков в C#, где этот MyClass<TType> нужно записать как MyClass&lt;TType&gt;. Это ужасно читать как исходный код. - person HotN; 18.12.2018