Commenti XML: i riferimenti dovrebbero essere completamente qualificati?

Question

Fondamentalmente, quando è veramente necessario (se non del tutto) utilizzare un xml completo, vedere riferimento:

<see cref="T:MyNamespace.Sub.MyType"/> //Option 1
<see cref="T:MyType"> //Option 2

Inoltre, che dire del riferimento agli oggetti .NET Framework?

<see cref="T:System.Collections.Generic.ICollection{T}"/> //Option 1
<see cref="T:ICollection{T}"/> //Option 2

Comprendo che gli elementi pienamente qualificanti consentiranno sempre a Sandcastle di Microsoft di collegare le cose correttamente, ma è necessario che tutto sia pienamente qualificato?

---

Nota a margine:Microsoft Sandcastle sarà in grado di collegarsi ai file della guida di .NET Framework o sto perdendo tempo facendo riferimento <see cref="T:System.Collections.Generic.ICollection{T}"/>?

Answer 1

Entrambi Giuseppe E Ben tocco punti utili ma penso che la mia recente esperienza con Sandcastle possa essere utile:

1. Quando compili il tuo progetto, Visual Studio di solito ti dirà immediatamente se il tuo riferimento è valido emettendo un avviso se non riesce a risolvere un riferimento nei tuoi commenti al documento, se si tratta di un riferimento ai tuoi tipi o ai tipi di sistema (e VS lo fa onorare le tue dichiarazioni "usando").

2. Nello scenario in cui un tipo locale maschera un tipo di sistema, ci sono due casi da considerare:la tua firma qualifica in modo univoco il tuo tipo (coperto da (1) sopra), oppure la tua firma duplica esattamente un tipo di sistema.Quest'ultimo caso richiede una disambiguazione esplicita qualificando pienamente il nome.

3. Hai accennato all'uso di specificare esplicitamente il prefisso del tipo di membro (per esempio."T:SuperWidget"), ma questo è più significativo di quanto la maggior parte delle persone creda:se si utilizza un prefisso del tipo di membro, i nomi completi sono necessarie.Questo è in realtà documentato su MSDN ma nel file molto stampa fine: vedi Elaborazione del file XML.E a peggiorare le cose, se ometti il ​​nome completo che ottieni nessun avvertimento in fase di compilazione(!);semplicemente non viene generato alcun collegamento nel rendering finale del Sandcastle.Ci sono altri problemi se specifichi esplicitamente un prefisso del tipo di membro: consulta il file Riferimenti disambiguanti e risolvibili sezione del mio articolo sui consigli pratici su Sandcastle, Addomesticare il castello di sabbia:Una guida per programmatori .NET per documentare il codice.

Answer 2

Non posso parlare per Sandcastle, ma in base alla mia esperienza con altri strumenti ad es.ReshArper, sembra che un tipo debba essere qualificato se a) non è in ambito o B) è ombreggiato da un altro tipo che è definito localmente.

In altre parole, se sei using System.Collections.Generic, non dovrai qualificarti ICollection{T}.Se ti capita di definire la propria interfaccia ICollection{T} nello stesso file, tuttavia, tu deve qualificare il primo (così come quest'ultimo, vieni a pensarci).

Answer 3

Non stai sprecando il tuo tempo in <see cref />-ing the Framework, a mio parere.Il fornitore di Guida Visual Studio dovrebbe essere in grado di intercettare e interpretare in fase di esecuzione quando viene effettuata la chiamata per quell'argomento della Guida.Non l'ho usato di recente, ma aveva lavorato abbastanza bene in passato.

Per quanto riguarda la qualifica pienamente, non è necessaria nella maggior parte degli scenari, ma dipende dai tuoi dadi, come Ben ha menzionato .Finché ciò che stai facendo riferimento è in ambito (e dovrebbe essere, come è probabile che tu lo stia usando se si fa riferimento, o si dovrebbe aggiungere l'utilizzo in modo che il tuo codice non stia usando il modulo completamente qualificato),Solo il tipo dovrebbe essere sufficiente.