Delimitadores de etiquetas de documentación (Guía de programación de C#)
Actualización: noviembre 2007
La utilización de comentarios de documentación XML requiere delimitadores, que indican al compilador el inicio y el final de un comentario de documentación. Puede utilizar los siguientes tipos de delimitadores con las etiquetas de documentación XML:
///
Ésta es la forma que se muestra en los ejemplos de documentación y que usan las plantillas de proyectos de Visual C#..gif "Nota")
Nota:El IDE de Visual Studio tiene una característica denominada Edición de comentarios automática, que inserta automáticamente las etiquetas <summary> y </summary> y sitúa el cursor entre ambas después de que haya escrito el delimitador /// en el Editor de código. El acceso a esta característica se encuentra en Formato, C#, Editor de texto, Opciones (Cuadro de diálogo) en sus páginas de propiedad del proyecto.
/** */
Delimitadores de múltiples líneas.
Existen algunas reglas de formato al usar los delimitadores /** */.
Si el resto de la línea que contiene el delimitador /** está en blanco, la línea no se procesa para comentarios. Si el primer carácter es un espacio en blanco, éste se omite y se procesa el resto de la línea. En caso contrario, todo el texto de la línea que se encuentra después del delimitador /** se procesa como parte del comentario.
Si en la línea que contiene el delimitador */ sólo hay espacio en blanco hasta dicho delimitador, se omite la línea. En caso contrario, el texto que hay en la línea hasta el delimitador */ se procesa como parte del comentario, sujeto a las reglas del patrón de coincidencia que se describen en el apartado siguiente:
Para las líneas que siguen a una que empieza con el delimitador /**, el compilador busca un patrón común al principio de cada línea que consiste en espacios en blanco opcionales y un asterisco (*), seguido de más espacios en blanco opcionales. Si el compilador encuentra un conjunto de caracteres común al principio de cada línea, omitirá este patrón para todas las líneas que se encuentran después del delimitador /** hasta la línea que contiene el delimitador */ y, posiblemente, incluyendo esta última.
Algunos ejemplos:
La única parte del siguiente comentario que se procesará es la línea que comienza con <summary>. Los dos formatos de etiquetas siguientes producirán los mismos comentarios:
/**
<summary>text</summary>
*/
/** <summary>text</summary> */
El compilador aplica un patrón de " * " para omitir al principio de la segunda y tercera líneas.
/**
* <summary>
* text </summary>*/
El compilador no encuentra ningún patrón en este comentario porque no hay ningún asterisco en la segunda línea. Por lo tanto, todo el texto que hay en la segunda y tercera líneas, hasta el delimitador */, se procesará como parte del comentario.
/**
* <summary>
text </summary>*/
El compilador no encuentra ningún patrón en este comentario por dos razones. En primer lugar, ninguna línea comienza con un número de espacios coherente delante del asterisco. En segundo lugar, la quinta línea comienza con una etiqueta, que no coincide con los espacios. Por lo tanto, todo el texto que hay a partir de la segunda línea hasta el delimitador */ se procesará como parte del comentario.
/**
* <summary>
* text
* text2
* </summary>
*/
Vea también
Tareas
Conceptos
Referencia
Comentarios de documentación XML (Guía de programación de C#)
/doc (Procesar comentarios de documentación) (Opciones del compilador de C#)
Comentarios de documentación XML (Guía de programación de C#)