Delimitadores para etiquetas de documentación en Visual C++

El uso de etiquetas de documentación requiere delimitadores, que indican al compilador dónde empieza y dónde acaba un comentario de documentación.

Puede usar los siguientes tipos de delimitadores con las etiquetas de documentación XML:

Delimitador	Descripción
///	Este es el formato que se muestra en los ejemplos de documentación y que usan las plantillas de proyecto de Visual Studio C++.
/** */	Se trata de delimitadores de múltiples líneas.

Hay varias reglas de formato cuando se usan los delimitadores /** */:

• En la línea que contiene el delimitador /**, si el resto de la línea es un espacio en blanco, la línea no se procesa en busca de comentarios. Si el primer carácter es espacio en blanco, se omite ese carácter de espacio en blanco y se procesa el resto de la línea. En caso contrario, todo el texto de la línea situado después del delimitador /** se procesa como parte del comentario.

• En la línea que contiene el delimitador */, si solo hay un espacio en blanco hasta el delimitador */, esa línea se omite. En caso contrario, el texto de la línea hasta el delimitador */ se procesa como parte del comentario y está sujeto a las reglas de coincidencia de patrones que se describen en el punto siguiente.

• Para las líneas después de la que comienza con el delimitador /**, el compilador busca un patrón común al principio de cada línea que consta de espacio en blanco opcional y un asterisco (*), seguido de más espacio en blanco opcional. Si el compilador encuentra un conjunto común de caracteres al principio de cada línea, omitirá este patrón para todas las líneas después del delimitador /**, hasta y, posiblemente, incluyendo la línea que contiene el delimitador */.

Ejemplos

• La única parte del comentario siguiente que se procesará es la línea que comienza con <summary>. Los dos formatos de etiqueta siguientes generarán los mismos comentarios:

  /**
  <summary>text</summary>
  */
  /** <summary>text</summary> */
  

• El compilador aplica un patrón de " * " para ignorar al principio de la segunda y la tercera línea.

  /**
   * <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 tanto, todo el texto de la segunda y la tercera línea, hasta */, 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, no hay ninguna línea que comience con un número coherente de espacios antes del asterisco. En segundo lugar, la quinta línea comienza con una pestaña, que no coincide con los espacios. Por tanto, todo el texto de la segunda línea, hasta */, se procesará como parte del comentario.

  /**
    * <summary>
    * text
   *  text2
     *  </summary>
  */
  

Consulte también

Documentación de XML