Я понял сегодня, что не знаю, как избежать символов в комментариях к С#. Я хочу документировать общий класс С#, но я не могу написать правильный пример, так как не знаю, как избежать символов < и >. Нужно ли использовать < и >? Мне не нравится, если это так, так как я хочу упростить чтение комментария в фактическом документе, поэтому мне не нужно создавать какой-то кодный документ, чтобы читать код примера.
Как избежать символов в комментариях С#?
Ответ 1
Если вам нужно избегать символов в комментариях XML, вам нужно использовать символьные сущности, поэтому < нужно будет экранировать как <, как в вашем вопросе.
Альтернативой экранированию является использование разделов CDATA для того же эффекта.
Как вы отметили, это создало бы хорошую документацию, но ужасный комментарий для чтения...
Ответ 2
В простых комментариях С# вы можете использовать любой символ (кроме */, если вы запустили комментарий с помощью /* или символ новой строки, если вы запустили комментарий с помощью //). Если вы используете комментарии XML, вы можете использовать раздел эту статью блога MSDN для получения дополнительной информации о комментариях XML на С#.
Например
/// <summary>
/// Here is how to use the class: <![CDATA[ <test>Data</test> ]]>
/// </summary>
Ответ 3
Вы сказали: "Я хочу, чтобы было легко прочитать комментарий в фактическом документе". Я согласен.
Разработчики проводят большую часть своей жизни в коде, не просматривая автоматически созданные документы. Они отлично подходят для сторонних библиотек, таких как составление диаграмм, но не для внутреннего развития, где мы работаем со всем кодом. Я потрясен тем, что MSFT не придумал решение, которое поддерживает разработчиков здесь лучше. У нас есть регионы, которые динамически расширяют/сворачивают код... почему мы не можем включить отображение комментариев на месте (между сырым текстом и обработанным комментарием XML или между сырым текстом и обработанным комментарием HTML)?. Похоже, что у меня должны быть некоторые элементарные возможности HTML в комментариях прологового метода/класса (красный текст, курсив и т.д.). Разумеется, IDE может немного обработать HTML-обработку, чтобы оживить встроенные комментарии.
Мое решение для решения проблемы: я меняю '<' на "{" и " > " на "}". Это, похоже, охватывает меня как типичный пример комментария стиля использования, включая ваш конкретный пример. Несовершенный, но прагматичный, учитывая проблему читаемости (и проблемы с раскраской комментариев IDE, которые возникают при использовании '<')
Ответ 4
XML-комментарии С# написаны в XML, поэтому вы должны использовать обычное экранирование XML.
Например...
<summary>Here is an escaped <token></summary>
Ответ 5
Я нашел приемлемое для жизни решение этой проблемы - это просто два примера: одна трудночитаемая версия в комментариях XML w/escape-символов и другая читаемая версия с использованием обычных комментариев //.
Простой, но эффективный.
Ответ 6
Лучше, чем использование {...} использует ≤... ≥ (знак меньше или равно, больше или равно знаку, U2264 и U2265 в Юникоде). Похоже, подчеркнутые угловые скобки, но все же определенные угловые скобки! И добавляет только пару байтов в ваш файл кода.
Ответ 7
Еще лучше попробовать U2280 и U2281 - просто скопируйте и вставьте из Список символов Юникода (раздел математических операторов).