Commenti XML - Sezione Documentazione MSDN "Nota" - Come si duplica?

Question

Fondamentalmente, nell'aiuto online MSDN, mi imbatto spesso in una sezione "nota", ma non posso per la vita di me capire come ottenere lo stesso output. Apparentemente non c'è no <note> etichetta. Qualcuno sa come farlo funzionare?

Idictionary (tkey, tvalue) - In questo esempio, se scendi alla sezione Osservazioni vedrai di cosa sto parlando.

Sto usando Sandcastle Help File Builder.

Answer 1

In realtà sia Sandcastle che Sandcastle Help File Builder supportano a <note> Elemento, anche se è estremamente ben nascosto! :-) È documentato solo in due luoghi di cui sono a conoscenza:

1. Il Guida ai commenti della documentazione XML Riferimento da Dyncity ... che apparentemente non è più disponibile sul Web-il link era http://www.dynicity.com/downloads/default.aspx.
2. UN Wallchart Accompagnando il mio articolo su semplice talk.com intitolato Taming Sandcastle: una guida del programmatore .NET alla documentazione del codice. Si noti che c'è un link nell'articolo per arrivare al wallchart, ma è in fondo all'articolo, quindi ho fornito collegamenti per entrambi qui. (Ho anche un riferimento alla guida di Dyncity nel mio articolo; comunicherò con la redazione per vedere se vogliono ospitare una copia locale della guida Dyncity ormai ormai e pubblicare un aggiornamento qui se lo fanno.)

Ecco tutta la documentazione che esiste per il <note> elemento. (Questo è dal mio wallchart; la guida della dinamica dice essenzialmente la stessa cosa, ma molto meno concisamente.)

Quella documentazione inadeguata è purtroppo tutto ciò che ho trovato <note>. Quindi ho eseguito una rapida prova, incorporando ogni tipo di nota all'interno di a Osservazioni sezione. Ecco cosa ha prodotto:

---

Cioè, con type="caution" Ottieni l'icona ed etichetta di cautela mentre gli altri valori di attributo a due tipi hanno prodotto la stessa icona ed etichetta nella mia particolare esempio. Sospetto che potrebbero esserci altre sfaccettature del suo uso profondamente sepolte nel sottobosco.

Answer 2

Per espandere il commento di CubRR sulla risposta di Bobby, ora c'è in realtà una documentazione ragionevolmente estesa sull'elemento Note in Sandcastle.

Esistono quattro categorie di note che puoi aggiungere a qualsiasi altro elemento XML predefinito come l'osservazione o gli elementi di riepilogo. Questi sono generali, avvertiti, sicurezza o linguaggio. La differenza principale tra loro sembra essere il tipo di icona che danno la nota e il titolo che la nota ha accanto all'icona. Puoi vedere l'elenco completo di tutti questi tipi di note qui.

Il seguente codice ha generato il risultato seguente per me:

/// <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>

Risultato:File di aiuto generato

Answer 3

C'è pochissima documentazione su Sandcastle, ma l'output della nota è potenzialmente da Sandcastle e non da tag di commento XML nativi di C#.

Puoi provare a utilizzare il seguente codice in cui si desidera inserire una sezione Nota e vedere quali output di Sandcastle (questo era supportato non è sicuro che sia cambiato):

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

Vedere: Aiuto di Microsoft Assistance Markup Language Longhorn per maggiori informazioni.