documentazione XML: utilizzando “cref” in , è questo accettabile o non è necessario?

Question

Sto usando GhostDoc per documentare i miei metodi, ecc ... e il suo lavoro bene, ma non riempie la <returns> ...

Qualcuno può dirmi quello che devo fare cioè

Se restituisce un oggetto chiamato "Ruoli", quindi

<returns>A role object see <see cref = "UserRole" /></returns>

o semplicemente

<returns>A role object</returns>

o

<returns>A role</returns>

So che i suoi suoni un po 'di essere troppo preciso, ma voglio cominciare corretto: -)

Prendiamo ad esempio un tipo di ritorno stringa standard di un nome utente

<returns>The user name</returns>

<returns>The user name, see <see cref = "system.string" /> </returns>

Answer 1

Prendendo i vostri spunti da MSDN ( esempio 1 , esempio 2 ):

<returns>A <see cref="string" /> that contains the username</returns>

<returns>An object that contains role information</returns>

Un generatore di documentazione includerà il tipo del valore di ritorno, quindi non è necessario incluso sempre; tuttavia, se ha senso (o se si vuole farlo notare) non è un problema di farlo, ma probabilmente nel flusso dichiarazione, piuttosto che come un separato "vedere X" l'istruzione.