.NET XML 文档中的参考前缀
我一直在尝试使用 XML 注释来完整记录类库的所有类型、方法、属性等，但遇到了涉及 cref 属性（由 see<例如 /code> 标签）。 遵循此 MSDN 页面的建议以及以下各种其他内容MSDN 和其他网站上的示例表明，每当使用 cref 标记指定引用值时，它都必须以某个对引用进行分类的标记作为前缀（例如“T:”表示类型和'M:' 表示方法）。
然而，在使用 Microsoft Sandcastle 时，我发现缺少这些前缀会对生成的文档（本例中为 CHM 帮助文件）产生影响。 包括前缀（在我认为的所有情况下），引用在页面上呈现为粗体文本...但不包括前缀，引用呈现为 API 引用中相应页面的锚点（链接）。 对我来说，推荐的给（全部？）引用添加前缀的方法给出了最无用的结果——为什么引用应该在一种情况下呈现为粗体并在另一种情况下链接？ 如果有人能阐明这一点，我将不胜感激。
I've been attempting to fully document all types, methods, properties, etc. of a class library using XML comments but have run into a curious effect involving the cref attribute (used by see tags for example). Going by the advice of this MSDN page as well as following various other examples on MSDN and other websites, it seems that whenever one specifies a reference value using the cref tag, it must be prefixed with a certain marker that classifies the refence (such as 'T:' for type and 'M:' for method).
Using Microsoft Sandcastle, however, I've observed that by missing out these prefixes there is an effect in the generated documentation (CHM help file in this case). Including prefixes (in all situations I belive), the reference is rendered on the page as bold text... Yet discluding the prefix the reference is rendered as an anchor (link) to the appropiate page within the API reference. It seems rather strange to me that the recommended method of prefixing (all?) references is giving the least useful result - why should the reference be rendered as bold in one case and linked in another? I would appreciate if someone could shed some light on this.
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（1）
这似乎是 sandcastle 中的错误
您使用的是哪个版本的 sandcastle？
这就是说最近的讨论似乎表明，至少对于系统类型，建议的方法是实际上避免使用限定名称，因为该答案中提出的示例完全删除了 T: 和 M: 因此，您的困惑并不意外或不常见。
本文档强烈暗示编译器可以在其中发现什么类型您指向的 /method/constant 会为您插入前缀。 你在xml中验证过这一点吗？
This appears to have been a bug in sandcastle
What version of sandcastle are you using?
That said recent discussions seem to indicate that, at least for System types, the suggested method is to actually avoid using the qualified names since the examples posited in that answer dropped the T: and M: entirely Your confusion is therefore not unexpected or uncommon.
This documentation strongly implies that the compiler, where it can spot what type/method/constant you're pointing to inserts the prefixes for you. Have you verified this in the xml?