Como faço para escapar caracteres em comentários c #?

112

Percebi hoje que não sei como escapar caracteres em comentários para C #. Desejo documentar uma classe C # genérica, mas não posso escrever um exemplo adequado, pois não sei como escapar dos caracteres <e >. Eu tenho que usar <e >? Não gosto se for esse o caso, pois quero facilitar a leitura do comentário no documento real, para não ter que gerar algum tipo de documento de código para poder ler o código de exemplo.

c#

— Tomas Jansson
fonte

1

Você poderia mostrar um comentário de exemplo?

— BoltClock

possível duplicata da string Xml em um comentário de resumo C #

— Mark Pim

1

@Mark: Você está certo, mas não é apenas XML ... Eu estava tentando escrever um exemplo para genéricos que não é XML, mas usa '<' e '>'. Mas a solução é a mesma para ambos.

— Tomas Jansson

Dada a popularidade dos modelos em C ++, Java, C # ... que possível desculpa a Microsoft tem para usar delimitadores XML incompletos? A costumeira falta de clareza e previsão.

— Rick O'Shea,

141

Se você precisa escapar caracteres em comentários XML, você precisa usar as entidades de caractere, portanto, <seria necessário escapar como <, como em sua pergunta.

A alternativa para escapar é usar CDATAseções, para o mesmo efeito.

Como você notou, isso produziria uma documentação de boa aparência, mas um comentário horrível de se ler ...

— Oded
fonte

19

Apenas para referência <seria <e >seria >. Por exemplo,List<string> myStringList = new List<string>();

— Arvo Bowen

@ArvoBowen Apenas no caso de alguém estar perdendo o óbvio, lt/ gtsignifica “menor que” / “maior que”, respectivamente.

— Lukas Juhrich

1

Curiosamente, apenas <precisa de ter escapado com <, >pode ficar como está: List<string> myStringList = new List<string>();. Pelo menos isso funciona no intellisense. Estranhamente, CDATA não funciona no intellisense. Eu não verifiquei como fica em documentos gerados automaticamente.

— Peter Huber

Pode confirmar que o VS 2013 não processa CDATAem intellisense. <torna o comentário difícil de ler.

— Alex

52

Em comentários simples em C #, você pode usar qualquer caractere (exceto */se você iniciou o comentário com /*, ou o caractere de nova linha se você iniciou o comentário com //). Se você estiver usando comentários XML, poderá usar uma seção CDATA para incluir os caracteres '<' e '>'.

Consulte este artigo do blog do MSDN para obter mais informações sobre comentários XML em C #.

Por exemplo

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

— Mark Pim
fonte

12

Você provavelmente está correto se deseja gerar documentos html de boa aparência, mas estou mais interessante em obter as dicas de intellisense no VS corretas, e para isso parece que tenho que usar escape XML. Mas 1 para a alternativa.

— Tomas Jansson

2

Hmm, lixo ilegível de máquina em meus comentários só ajuda se tomarmos o tempo para criar nosso arquivo de documento quando a vasta, vasta, vasta (já mencionei?) Maioria dos casos de uso está lendo os comentários na fonte (de preferência uma interface) .

— Rick O'Shea,

19

Você disse "Quero facilitar a leitura do comentário no documento real". Concordo.

Os desenvolvedores passam a maior parte de suas vidas no código , não lendo documentos gerados automaticamente. Esses são ótimos para bibliotecas de terceiros, como gráficos, mas não para desenvolvimento interno, onde trabalhamos com todo o código. Estou meio chocado que a MSFT não tenha apresentado uma solução que ofereça melhor suporte aos desenvolvedores aqui. Temos regiões que expandem / reduzem o código dinamicamente ... por que não podemos ter uma alternância de renderização de comentário no local (entre texto bruto e comentário XML processado ou entre texto bruto e comentário HTML processado) ?. Parece que eu deveria ter alguns recursos HTML elementares em meus comentários de prólogo de método / classe (texto em vermelho, itálico, etc). Certamente um IDE poderia funcionar um pouco da mágica do processamento de HTML para animar os comentários embutidos.

Minha solução hack-of-a-solution : eu altero '<' para "{" e '> "para"} ". Isso parece me cobrir para o exemplo típico de comentário de estilo de uso, incluindo seu exemplo específico. Imperfeito, mas pragmático dado o problema de legibilidade (e problemas com a coloração de comentários do IDE que ocorrem ao usar '<')

— Dave
fonte

5

Seu "truque de solução" parece ser mais correto do que você pensa. De acordo com isso, o compilador reconhece as chaves como colchetes angulares e as vincula corretamente .

— RubberDuck de

8

Os comentários XML em C # são escritos em XML, portanto, você usaria escape XML normal.

Por exemplo...

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

— Bob Black
fonte

5

Eu descobri que uma solução viável para este problema é simplesmente incluir dois exemplos: uma versão difícil de ler nos comentários XML com caracteres de escape e outra versão legível usando //comentários convencionais .

Simples mas efetivo.

— HolySamosa
fonte

0

Melhor do que usar {...} é usar ≤ ... ≥ (sinal de menor ou igual, sinal de maior ou igual, U2264 e U2265 em Unicode). Parece com colchetes angulares sublinhados, mas ainda definitivamente colchetes angulares! E apenas adiciona alguns bytes ao seu arquivo de código.

— Mick Bruno
fonte

0

Melhor ainda, tente U2280 e U2281 - basta copiar e colar da Lista de caracteres Unicode (seção de operadores matemáticos).

— Paul Coulson
fonte

Operadores Unicode são OK quando são usados para representar operadores matemáticos reais, ruins se são usados em trechos de código que estão em um comentário (por exemplo List<int>). Pense, por exemplo, em copiar e colar o snippet de código.

— Palec

você pode fornecer um exemplo de como usar isso em um comentário? nunca usou caracteres Unicode de fato

— ClementWalter

1

Copie e cole o caractere conforme descrito acima.

— Paul Coulson de