Comment spécifier le type dans un commentaire XML commentaire

Question

Dans mon commentaire C # XML <return> Commentaire, j'aimerais la sortie (j'utilise Sandcastle) pour spécifier le type qui est renvoyé, mais je ne peux pas savoir comment le faire.

Exemple PSUedo:

///<summary>
///Serves as a hash function for a particular type.
///</summary>
///<returns **Type="System.Int32"**>
///A hash code for the current Object.
///</returns>
public virtual int GetHashCode(){...}

L'exemple ci-dessus est une maquette de ce que je suppose de dire à Sandcastle comment spécifier le type de retour qui est documenté dans le Syntax Section de la documentation - ce n'est pas le cas.

Pour plus de clarté, voici une capture d'écran de la documentation de MSDN sur le Gethastcode () Méthode qui montre le type de retour pour lequel je tire.

Devons-nous spécifier manuellement le type, ou pouvons-nous spécifier un type (similaire à l'exemple simulé) et laisser le rason à sable déterminer comment afficher / formater la sortie - similaire à la façon dont Sandcastle affiche / formats automatiquement le type des paramètres via le <param> étiquette.

Answer 1

Ce post (Juillet 2011) a une réponse d'Eric Woodruff (auteur SHFB) concernant l'absence du type de retour affiché dans le <return> étiquette:

Sandcastle ne rend pas les informations de type pour les informations de retour et je ne pense pas qu'elle ait jamais eu. À condition que les informations soient dans le fichier d'informations de réflexion, les transformations XSL pourraient être modifiées pour les rendre. Je n'ai pas le temps de l'examiner maintenant, mais je peux à un moment donné savoir si c'est possible.

Je suppose que la réponse officielle à mon PO est; Sandcastle n'a pas de moyen automatique de spécifier le type de retour mais, comme Skeet déjà mentionné, il peut Soyez possible pour y parvenir en modifiant les transformations XSL.

Answer 2

Vous ne devriez pas avoir besoin de le spécifier dans la documentation XML - après tout, ce serait redondant, étant donné que c'est dans la déclaration de la méthode.

Je soupçonne qu'il s'agit de peaufiner le style de sable si vous le voulez vraiment - mais le trouvez-vous particulièrement utile? Ce n'est pas comme si les utilisateurs ne peuvent pas simplement cliquer sur le type de retour dans la signature de la méthode. (Au moins, c'est ce qui semble être le cas pour le style prototype de SHFB. Voir le Documentation de Noda Time pour un exemple de ce à quoi cela ressemble.)

Dans MSDN, puis la signature de la méthode n'a pas avoir des liens (du moins pas dans Chrome; je ne sais pas si c'est différent dans IE) mais personnellement je préférerais que ce soit dans la signature Au lieu d'encombrer la documentation réelle.