Préfixes de référence dans la documentation XML .NET

Question

J'ai essayé de documenter complètement tous les types, méthodes, propriétés, etc. d'une bibliothèque de classes en utilisant des commentaires XML mais j'ai couru un curieux effet impliquant l'attribut cref (utilisé par les balises see par exemple). En suivant les conseils de this MSDN page ainsi qu'en suivant divers autres exemples sur MSDN et d'autres sites Web, il semble que chaque fois que l'on spécifie une valeur de référence en utilisant la balise cref, elle doit être précédée d'un marqueur qui classe la référence (T : 'pour le type et' M: 'pour la méthode). En utilisant Microsoft Sandcastle, cependant, j'ai remarqué qu'en omettant ces préfixes il y a un effet dans la documentation générée (fichier d'aide CHM dans ce cas). Y compris les préfixes (dans toutes les situations que je crois), la référence est rendue sur la page en texte gras ... Pourtant, en dévoilant le préfixe, la référence est rendue en tant qu'annexe (lien) à la page appropriée dans la référence API. Il me semble plutôt étrange que la méthode recommandée de préfixation (toutes?) Références donne le résultat le moins utile - pourquoi la référence devrait-elle être rendue audacieuse dans un cas et liée dans une autre? J'apprécierais que quelqu'un puisse faire la lumière sur ce sujet.

Answer 1

Cela semble avoir été un bug in sandcastle

Quelle version de Sandcastle utilisez-vous? Cela dit recent discussions Cela indique que, au moins pour les types de systèmes, la méthode suggérée est d'éviter réellement d'utiliser les noms qualifiés puisque les exemples posés dans cette réponse ont complètement abandonné T: et M: Votre confusion n'est donc pas inattendue ou rare.

This documentation implique fortement que le compilateur, où il peut repérer quel type/méthode/constante que vous pointez à insère les préfixes pour vous. Avez-vous vérifié cela dans le fichier XML?