¿Cómo puedo escapar de los caracteres en los comentarios de C #?

112

Hoy me di cuenta de que no sé cómo escapar de los caracteres en los comentarios para C #. Quiero documentar una clase C # genérica, pero no puedo escribir un ejemplo adecuado porque no sé cómo escapar de los caracteres <y >. ¿Tengo que usar <y >? No me gusta si ese es el caso, ya que quiero facilitar la lectura del comentario en el documento real para no tener que generar algún tipo de documento de código para poder leer el código de ejemplo.

c#

— Tomas Jansson
fuente

1

¿Podría mostrar un comentario de ejemplo?

— BoltClock

posible duplicado de la cadena Xml en un comentario de resumen de C #

— Mark Pim

1

@Mark: Tienes razón, pero no es solo XML ... Estaba tratando de escribir un ejemplo para genéricos que no es XML pero usa '<' y '>'. Pero la solución es la misma para ambos.

— Tomas Jansson

Dada la popularidad de las plantillas en C ++, Java, C # ... ¿qué posible excusa tiene Microsoft para usar delimitadores XML a medias? La habitual falta de claridad y previsión.

— Rick O'Shea

141

Si necesita escapar caracteres en comentarios XML, debe usar las entidades de caracteres, por <lo que deberá usar el escape como <, como en su pregunta.

La alternativa a escapar es usar CDATAsecciones, con el mismo efecto.

Como notó, esto produciría una buena documentación, pero un comentario horrible para leer ...

— Oded
fuente

19

Solo como referencia <sería <y >sería >. Por ejemploList<string> myStringList = new List<string>();

— Arvo Bowen

@ArvoBowen En caso de que a alguien se le escape lo obvio, lt/ gtrepresento "menor que" / "mayor que", respectivamente.

— Lukas Juhrich

1

Curiosamente, sólo <tiene que llegar escapado con <, >puede permanecer como es: List<string> myStringList = new List<string>();. Al menos esto funciona en intellisense. Curiosamente, CDATA no funciona en intellisense. No verifiqué cómo se ve en documentos generados automáticamente.

— Peter Huber

Puede confirmar que VS 2013 no se procesa CDATAen intellisense. <hace que el comentario sea difícil de leer.

— Alex

52

En los comentarios simples de C # puede usar cualquier carácter (excepto */si comenzó el comentario con /*, o el carácter de nueva línea si comenzó el comentario con //). Si está utilizando comentarios XML, puede utilizar una sección CDATA para incluir caracteres '<' y '>'.

Consulte este artículo del blog de MSDN para obtener más información sobre los comentarios XML en C #.

Por ejemplo

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

— Mark Pim
fuente

12

Probablemente tenga razón si desea generar documentos html de buen aspecto, pero me interesa más obtener los consejos de intellisense en VS correctos, y para eso parece que tengo que usar XML escaping. Pero +1 para la alternativa.

— Tomas Jansson

2

Hmm, la basura ilegible de la máquina en mis comentarios solo ayuda si nos tomamos el tiempo para construir nuestro archivo de documento cuando la vasta, vasta, vasta (¿mencioné vasta?) Mayoría de casos de uso está leyendo los comentarios en la fuente (preferiblemente una interfaz) .

— Rick O'Shea

19

Dijo "Quiero que sea más fácil leer el comentario en el documento real". Estoy de acuerdo.

Los desarrolladores pasan la mayor parte de sus vidas en el código , no examinando documentos generados automáticamente. Son excelentes para bibliotecas de terceros como gráficos, pero no para el desarrollo interno en el que trabajamos con todo el código. Estoy un poco sorprendido de que MSFT no haya encontrado una solución que soporte mejor a los desarrolladores aquí. Tenemos regiones que expanden / contraen código dinámicamente ... ¿por qué no podemos tener un conmutador de representación de comentarios en el lugar (entre texto sin formato y comentario XML procesado o entre texto sin formato y comentario HTML procesado)? Parece que debería tener algunas capacidades HTML elementales en los comentarios del prólogo de mi método / clase (texto rojo, cursiva, etc.). Sin duda, un IDE podría funcionar con un poco de magia de procesamiento HTML para animar los comentarios en línea.

Mi solución de pirateo de una solución : cambio '<' a "{" y '> "a"} ". Eso parece cubrirme para el típico comentario de estilo de uso de ejemplo, incluido su ejemplo específico. Imperfecto, pero pragmático dado el problema de legibilidad (y los problemas con el color de los comentarios del IDE que surgen cuando se usa '<')

— Dave
fuente

5

Su "truco de una solución" parece ser más correcto de lo que cree. De acuerdo con esto, el reconocedor del compilador coloca llaves como corchetes angulares y las enlaza correctamente .

— RubberDuck

8

Los comentarios XML de C # están escritos en XML, por lo que usaría el escape XML normal.

Por ejemplo...

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

— Bob negro
fuente

5

Encontré una solución aceptable para este problema simplemente incluir dos ejemplos: una versión difícil de leer en los comentarios XML con caracteres de escape y otra versión legible con //comentarios convencionales .

Simple, pero efectivo.

— SantoSamosa
fuente

0

Mejor que usar {...} es usar ≤ ... ≥ (signo menor o igual, signo mayor o igual, U2264 y U2265 en Unicode). Parecen paréntesis angulares subrayados, ¡pero definitivamente corchetes angulares! Y solo agrega un par de bytes a su archivo de código.

— Mick Bruno
fuente

0

Incluso mejor pruebe U2280 y U2281: simplemente copie y pegue desde la Lista de caracteres Unicode (sección de operadores matemáticos).

— Paul Coulson
fuente

Los operadores Unicode están bien cuando se usan para representar operadores matemáticos reales, y son deficientes si se usan en fragmentos de código que se encuentran en un comentario (por ejemplo List<int>). Piense, por ejemplo, en copiar y pegar el fragmento de código.

— Palec

¿Puede proporcionar un ejemplo de cómo usar esto en un comentario? De hecho, nunca usó caracteres Unicode

— ClementWalter

1

Copie y pegue el carácter como se describe arriba.

— Paul Coulson