Comentarios de XML - Sección "Nota" de documentación de MSDN - ¿Cómo duplica esto?

Question

Básicamente, en la ayuda en línea de MSDN a menudo me encuentro con una sección de "nota", pero no puedo para mí descubrir cómo obtener el mismo resultado. Aparentemente no hay <note> etiqueta. ¿Alguien sabe cómo hacer que esto funcione?

Idictionary (tkey, tvalue) - En este ejemplo, si vas a la sección de comentarios, verás de lo que estoy hablando.

Estoy usando Sandcastle Help File Builder.

Answer 1

En realidad, tanto el sandcastle como el sandcastle ayudan a los archivos que admiten un <note> ¡Elemento, aunque está extremadamente bien escondido! :-) Solo se documenta en dos lugares que conozco:

1. los Guía de comentarios de documentación XML referencia de Dyncity ... que aparentemente ya no está disponible en la web; el enlace solía ser http://www.dynicity.com/downloads/default.aspx.
2. A gráfico mural Acompañando mi artículo en Simple-Talk.com titulado Taming Sandcastle: una guía del programador de .NET para documentar su código. Tenga en cuenta que hay un enlace en el artículo para llegar al cuadro de pared, pero está en la parte inferior del artículo, así que he dado enlaces para ambos aquí. (También tengo una referencia a la guía de Dyncity en mi artículo; me comunicaré con el personal editorial para ver si quieren alojar una copia local de la guía de Dyncity ahora orfanada y publicaré una actualización aquí si lo hacen).

Aquí hay sobre toda la documentación que hay para el <note> elemento. (Esto es de mi diagrama de pared; la Guía de Dyncity dice esencialmente lo mismo pero mucho menos concisamente).

Esa documentación inadecuada es lamentablemente todo lo que he encontrado <note>. Así que realizé una prueba rápida, incrustando cada tipo de nota dentro de un Observaciones sección. Esto es lo que produjo:

---

Es decir, con type="caution" Obtiene el icono de precaución y la etiqueta, mientras que los otros dos valores de atributo de dos tipos produjeron el mismo icono de nota y etiqueta en mi ejemplo particular. Sospecho que puede haber otras facetas de su uso profundamente enterrados en la maleza.

Answer 2

Para ampliar el comentario de Cubrr sobre la respuesta de Bobby, en realidad, ahora hay una documentación razonablemente extensa en el elemento de nota en Sandcastle.

Hay cuatro categorías de notas que puede agregar a cualquier otro elemento XML predeterminado, como la observación o los elementos de resumen. Estos son generales, advertidos, de seguridad o idioma. La principal diferencia entre ellos parece ser el tipo de icono que dan la nota y el título que la nota tiene junto al icono. Puede ver la lista completa de todos estos tipos de notas aquí.

El siguiente código generó el siguiente resultado para mí:

/// <remarks>
/// <note type="note">
/// This is a note in a remark. It is a General note.
/// </note>
/// <note type="tip">
/// This is a tip note in a remark. It is a General note.
/// </note>
/// <note type="implement">
/// This is a implement note in a remark. It is a General note.
/// </note>
/// <note type="caller">
/// This is a caller note in a remark. It is a General note.
/// </note>
/// <note type="inherit">
/// This is a inherit note in a remark. It is a General note.
/// </note>
/// <note type="caution">
/// This is a caution note in a remark. It is a Cautionary note.
/// </note>
/// <note type="important">
/// This is a important note in a remark. It is a Cautionary note.
/// </note>
/// <note type="security">
/// This is a security note in a remark. It is a Security note.
/// </note>
/// <note type="cs">
/// This is a cs note in a remark. It is a Language note.
/// </note>
/// </remarks>

Resultado:Archivo de ayuda generado

Answer 3

Hay muy poca documentación en Sandcastle, pero la salida de nota es potencialmente de Sandcastle y no las etiquetas de comentarios XML nativas de C#.

Puede intentar usar el siguiente código donde desea colocar una sección de notas y ver qué salidas de sandcastle (esto solía ser compatible no seguro si ha cambiado):

<alert class="note">This is a 'alert class=note'</alert>

Ver: Microsoft Assistance Markup Language Longhorn Ayuda para más información.