对部分类/方法进行 XML 注释
用于生成 API 文档的工具是否有一种标准方法可以处理对部分类进行 XML 样式注释？基本上，应该如何注释部分类/方法，以便生成的帮助文档不会被破坏？这个问题可能会因所使用的工具而异，在这种情况下，我猜最重要的两个工具是：
- Visual Studio 的内置方法来创建 XML 文档
- Microsoft 的 Sandcastle
我不希望我的 XML 文档变得很时髦全部
/// <summary>Some Foo class</summary>
public partial class Foo { ... }
/// <summary>Some Foo class that implements some interface.</summary>
public partial class Foo : ISomeInterface { ... }
Is there a standard way that the tools used to generate the API documents handle having XML Style comments on partial classes? Basically, how should one comment a partial class/method so that the resulting help documents aren't mangled? This question could vary depending on the tool used, in which case, I guess the two tools that are the most important are:
- Visual Studio's built in method to create XML documentation
- Microsoft's Sandcastle
I don't want my XML documentation to come out funky is all
/// <summary>Some Foo class</summary>
public partial class Foo { ... }
/// <summary>Some Foo class that implements some interface.</summary>
public partial class Foo : ISomeInterface { ... }
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（1）
最佳实践是为仅其中 1 个部分定义提供 XML 注释。不需要将 1 个类的公共评论分成 2 个位置。 （当然，在每个部分定义中添加常规注释仍然有意义。）
Visual Studio 的工作方式是一个部分定义中的注释将覆盖另一个部分定义中的注释。您可以通过使用不同的 XML 注释创建同一类的 2 个部分定义来确认这一点，然后创建此类型的变量。智能感知将仅显示 1 个 XML 注释。
这也是任何使用 Visual Studio 生成的 XML 注释文件的文档工具（包括 Sandcastle）的行为。
The best practice is to give XML comments to just 1 of the partial definitions. There should be no need to split public comments for 1 class into 2 places. (Of course regular comments still make sense to have in each partial definition.)
The way Visual Studio works is that a comment in one partial definition will override the other. You can confirm this by creating 2 partial definitions of the same class with different XML comments, then create a variable of this type. The intellisense will show only 1 of the XML comments.
This will also be the behavior of any documentation tool that uses the XML comments file generated by Visual Studio, which includes Sandcastle.