Как мне экранировать символы в комментариях c #?

112

Сегодня я понял, что не знаю, как экранировать символы в комментариях для C #. Я хочу , чтобы задокументировать общий C # класса, но я не могу написать правильный пример , так как я не знаю , как избежать <и >символов. Я должен использовать <и >? Мне не нравится, если это так, поскольку я хочу упростить чтение комментария в реальном документе, чтобы мне не нужно было создавать какой-то документ с кодом, чтобы иметь возможность читать пример кода.

c#

— Томас Янссон
источник

1

Не могли бы вы показать пример комментария?

— BoltClock

возможный дубликат строки Xml в сводном комментарии C #

— Марк Пим

1

@Mark: Вы правы, но это не только XML ... Я пытался написать пример для дженериков, который не является XML, но использует '<' и '>'. Но решение одинаково для обоих.

— Томас Янссон

Учитывая популярность шаблонов в C ++, Java, C # ... какое возможное оправдание есть у Microsoft для использования полусырых XML-разделителей? Обычное отсутствие ясности и дальновидности.

— Рик О'Ши

141

Если вам нужно экранировать символы в комментариях XML, вам необходимо использовать символьные сущности, поэтому <их нужно будет экранировать как <, как в вашем вопросе.

Альтернативой экранированию является использование CDATAразделов с тем же эффектом.

Как вы заметили, это приведет к созданию красивой документации, но ужасный комментарий для чтения ...

— Одед
источник

19

Просто для справки <был бы <и >был бы >. В качестве примераList<string> myStringList = new List<string>();

— Арво Боуэн

@ArvoBowen На всякий случай, если кто-то упускает из виду очевидное, lt/ gtозначает «меньше чем» / «больше чем» соответственно.

— Лукас Юрих

1

Интересно, что только <нужно , чтобы отделался <, >может остаться , как это: List<string> myStringList = new List<string>();. По крайней мере, это работает в intellisense. Как ни странно, CDATA в intellisense не работает. Я не проверял, как это выглядит в автоматически созданных документах.

— Питер Хубер,

Можно подтвердить, что VS 2013 не отображается CDATAв intellisense. <делает комментарий трудным для чтения.

— Alex

52

В простых комментариях C # вы можете использовать любой символ (за исключением того, */если вы начали комментарий с /*или символа новой строки, если вы начали комментарий с //). Если вы используете комментарии XML, вы можете использовать раздел CDATA для включения символов «<» и «>».

См. Эту статью блога MSDN для получения дополнительной информации о комментариях XML в C #.

Например

/// <summary>
/// Here is how to use the class: <![CDATA[ <test>Data</test> ]]>
/// </summary>

— Марк Пим
источник

12

Вы, вероятно, правы, если хотите создавать красивые html-документы, но мне больше интересно получить правильные подсказки intellisense в VS, и для этого мне кажется, что мне нужно использовать экранирование XML. Но +1 за альтернативу.

— Томас Янссон

2

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

— Рик О'Ши

19

Вы сказали: «Я хочу упростить чтение комментария в самом документе». Я согласен.

Разработчики проводят большую часть своей жизни в коде , не просматривая автоматически созданные документы. Они отлично подходят для сторонних библиотек, таких как создание диаграмм, но не для внутренней разработки, когда мы работаем со всем кодом. Я в некотором роде шокирован тем, что MSFT не представила решения, которое лучше поддерживало бы разработчиков. У нас есть области, которые динамически расширяют / сворачивают код ... почему у нас не может быть переключателя рендеринга комментариев на месте (между необработанным текстом и обработанным комментарием XML или между необработанным текстом и обработанным комментарием HTML) ?. Похоже, у меня должны быть некоторые элементарные возможности HTML в комментариях к прологу моего метода / класса (красный текст, курсив и т. Д.). Конечно, IDE могла бы немного поработать с обработкой HTML, чтобы оживить встроенные комментарии.

Мое решение для взлома решения : я меняю '<' на "{" и '> "на"} ". Кажется, это покрывает меня для типичного примера стиля использования комментария, включая ваш конкретный пример. Несовершенно, но прагматично учитывая проблему с удобочитаемостью (и проблемы с раскраской комментариев IDE, возникающие при использовании '<')

— Дэйв
источник

5

Ваш «взлом решения» кажется более правильным, чем вы думаете. В соответствии с этим компилятор распознает фигурные скобки как угловые и правильно их связывает .

— RubberDuck

8

Комментарии C # XML написаны в XML, поэтому вы должны использовать обычное экранирование XML.

Например...

<summary>Here is an escaped &lt;token&gt;</summary>

— Боб Блэк
источник

5

Я нашел приемлемое решение этой проблемы, просто включив два примера: одну трудную для чтения версию в XML-комментариях с escape-символами и другую читаемую версию с использованием обычных //комментариев.

Простой, но эффективный.

— HolySamosa
источник

0

Лучше, чем использовать {...}, использовать ≤ ... ≥ (знак меньше или равно, знак больше или равно, U2264 и U2265 в Unicode). Выглядит как подчеркнутые угловые скобки, но все же определенно угловые скобки! И добавляет всего пару байтов в ваш файл кода.

— Мик Бруно
источник

0

Еще лучше попробуйте U2280 и U2281 - просто скопируйте и вставьте из списка символов Unicode (раздел математических операторов).

— Пол Коулсон
источник

Операторы Unicode подходят, когда они используются для представления реальных математических операторов, и плохо, если они используются в фрагментах кода, которые случайно находятся в комментариях (например List<int>). Подумайте, например, о копировании фрагмента кода.

— Palec

можете ли вы привести в комментарии пример того, как это использовать? на самом деле никогда не использовал символы Unicode

— ClementWalter

1

Скопируйте и вставьте символ, как описано выше.

— Пол Коулсон