Commentaires XML - Les références devraient-elles être pleinement qualifiées?

Question

Fondamentalement, quand est-il vraiment nécessaire (le cas échéant) d'utiliser un XML entièrement qualifié Voir référence:

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

En outre, qu'en est-il de référence aux objets .NET Framework?

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

Je comprends que les articles entièrement qualifiés permettront toujours à Sandcastle de Microsoft de relier les choses correctement, mais est-il nécessaire que tout soit pleinement qualifié?

---

Sidenote: Microsoft Sandcastle pourra-t-il créer un lien vers les fichiers d'aide .NET Framework ou je perds mon temps en faisant référence <see cref="T:System.Collections.Generic.ICollection{T}"/>?

Answer 1

Tous les deux Joseph et Ben Touchez des points utiles, mais je pense que ma récente expérience de sable peut être utile:

1. Lorsque vous compilez votre projet Visual Studio vous dira généralement immédiatement si votre référence est valable en émettant un avertissement s'il ne peut pas résoudre une référence dans vos documents Doc, s'il s'agit d'une référence à vos propres types ou aux types de systèmes (et vs fait Honorez vos déclarations «utilisant»).

2. Dans le scénario d'avoir un type local masquant un type de système, il existe deux cas à considérer: votre signature qualifie de manière unique votre type (couvert par (1) ci-dessus), ou votre signature duplique exactement un type de système. Ce dernier cas nécessite une désambiguïsation explicite en qualifiant pleinement le nom.

3. Vous avez abordé l'utilisation de spécifier explicitement le Préfixe de type membre (par exemple "T: SuperWidget"), mais c'est plus important que la plupart des gens ne le pensent: si vous utilisez un préfixe de type membre, les noms entièrement qualifiés sont requises. Ceci est en fait documenté sur MSDN mais dans le très Fine impression - voir Traitement du fichier XML. Et pour aggraver les choses, si vous omettez le nom entièrement qualifié que vous obtenez pas d'avertissement Au moment de la construction (!); Tout simplement aucun lien n'est généré dans le rendu final de sable. Il y a d'autres problèmes si vous spécifiez explicitement un préfixe de type membre - voir le Désambigir et résoudre les références Section de mon article sur les conseils pratiques de sable, Taming Sandcastle: un guide du programmeur .NET pour documenter votre code.

Answer 2

Je ne peux pas parler pour Sandcastle, mais sur la base de mon expérience avec d'autres outils, par exemple Resharper, il semble qu'un type doit être qualifié si a) il n'est pas dans la portée ou b) il est ombragé par un autre type qui est plus défini localement.

En d'autres termes, si vous êtes using System.Collections.Generic, alors vous n'aurez pas à vous qualifier ICollection{T}. Si vous définissez le vôtre ICollection{T} interface dans le même fichier, cependant, vous sera doivent qualifier le premier (ainsi que le second, à y penser).

Answer 3

Vous ne perdez pas votre temps <see cref />-ing le cadre, à mon avis. Le fournisseur d'aide Visual Studio devrait être en mesure d'intercepter et d'interpréter au moment de l'exécution lorsque l'appel est passé pour ce sujet d'aide. Je ne l'ai pas utilisé récemment, mais cela avait très bien fonctionné dans le passé.

Quant à des qualifications pleinement, elle n'est pas nécessaire dans la plupart des scénarios, mais dépend de vos utilisateurs, comme Ben a mentionné. Tant que ce que vous faites référence est dans la portée (et devrait l'être, car vous êtes susceptible de l'utiliser si vous le référez, ou vous devez ajouter l'utilisation afin que votre code n'utilise pas le formulaire entièrement qualifié), Le type doit suffire.