generate - params comments c#
¿Cómo puedo escapar de los personajes en los comentarios de c#? (7)
Me di cuenta hoy que no sé cómo escapar de los personajes en los comentarios de C #. Quiero documentar una clase C # genérica, pero no puedo escribir un ejemplo adecuado ya que no sé cómo escapar de los caracteres < y > . ¿Tengo que usar < y > ? No me gusta si ese es el caso, ya que quiero que sea fácil leer el comentario en el documento real, así no tengo que generar algún tipo de documento de código para poder leer el código de ejemplo.
En 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 usar una sección CDATA para incluir los caracteres ''<'' y ''>''.
Consulte este artículo de 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>
He encontrado que una solución habitable para este problema es simplemente incluir dos ejemplos: una versión difícil de leer en los comentarios XML con caracteres de escape y otra versión legible usando // comentarios convencionales.
Simple, pero efectivo.
Los comentarios de C # XML están escritos en XML, por lo que usaría escapes XML normales.
Por ejemplo...
<summary>Here is an escaped <token></summary>
Mejor aún intente con U2280 y U2281, simplemente copie y pegue de la lista de caracteres Unicode (sección de operadores matemáticos).
Mejor que usar {...} es usar ≤ ... ≥ (menos que o igual a signo, mayor o igual a signo, U2264 y U2265 en Unicode). ¡Parece corchetes angulosos subrayados pero definitivamente son corchetes angulares! Y solo agrega un par de bytes a su archivo de código.
Si necesita escapar de los caracteres en los comentarios de XML, debe usar las entidades de caracteres, por lo que < debería escaparse como < como en tu pregunta.
La alternativa para escapar es usar secciones CDATA , con el mismo efecto.
Como notaste, esto produciría buena documentación, pero un comentario horrible para leer ...
Usted dijo "Quiero que sea 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 , sin leer los documentos generados automáticamente. Esos son geniales para bibliotecas de terceros, como los gráficos, pero no para el desarrollo interno donde trabajamos con todo el código. Estoy algo sorprendido de que MSFT no haya encontrado una solución que respalde mejor a los desarrolladores aquí. Tenemos regiones que expanden / contraen el código dinámicamente ... ¿por qué no podemos tener un alternar representación de comentarios en el lugar (entre el texto sin procesar y el comentario XML procesado o entre el texto sin procesar y el comentario HTML procesado) ?. Parece que debería tener algunas capacidades elementales de HTML en mis comentarios de prólogo de método / clase (texto en rojo, cursiva, etc.). Seguramente un IDE podría trabajar un poco de magia de procesamiento de HTML para animar los comentarios en línea.
Mi solución de hack-of-a-solution : cambio ''<'' a "{" y ''> "a"} ". Eso parece cubrirme el típico ejemplo de uso de estilo de uso, incluido su ejemplo específico. Imperfecto, pero pragmático dado el problema de legibilidad (y problemas con el coloreado de comentario IDE que se produce al usar ''<'')