选择性地抑制 C# 中的 XML 代码注释？答案

【问题标题】：Selectively suppress XML Code Comments in C#?选择性地抑制 C# 中的 XML 代码注释？
【发布时间】：2010-03-19 00:59:37
【问题描述】：

我们向外部客户提供了许多程序集，但并非所有公共 API 都得到官方支持。例如，由于不是最优的设计选择，有时必须从程序集中公开一个类型才能使我们的其余代码正常工作，但我们不希望客户使用该类型。传达缺乏支持的一部分是不以 XML cmets 的形式提供任何智能感知。

有没有办法选择性地抑制 XML cmets？我正在寻找除了忽略警告 1591 之外的其他东西，因为它是一个长期维护问题。

示例：我有一个包含公共类 A 和 B 的程序集。A 得到官方支持，应该有 XML 文档。 B 不适用于外部使用，不应记录在案。我可以打开 XML 文档，然后取消警告 1591。但是当我稍后添加官方支持的 C 类时，我希望编译器告诉我我搞砸了并且未能添加 XML 文档。如果我在项目级别取消了 1591，则不会发生这种情况。我想我可以跨整个班级#pragma，但似乎应该有更好的方法来做到这一点。

【问题讨论】：

标签： c# xml documentation code-documentation

【解决方案1】：

创建此类方法internal，并将[assembly: InternalsVisibleTo("AssemblyName")] 属性添加到公开它们的程序集。

【讨论】：

唉，我正在处理大量代码，所以这不切实际。
@Mike Post 将公共 API 与私有 API 分开应该是您从第一天开始就最关心的问题，如果不是，那么您需要进行大量重构。对此没有快速解决方案，John 建议的内容实际上很简洁，不知道您可以将内部方法暴露给其他 friend 程序集。

【解决方案2】：

不提供智能感知怎么样？

///<summary>A documentation</summary> 
public class A { }

///<summary>B documentation. This class is not supported...</summary> 
[EditorBrowsable(EditorBrowsableState.Advanced)]
public class B { }

///<summary>C documentation</summary> 
public class C { }

这样，您仍然可以记录不受支持的类（内部用户也很重要！）并且让您的外部用户在智能感知上看不到它们。在内部，您可以使 Visual Studio 能够“看到”这些高级构造。 EditorBrowsableAttribute 的页面告诉我们如何：

在 Visual C# 中，您可以使用工具 | 下的隐藏高级成员设置来控制高级属性何时出现在 IntelliSense 和属性窗口中。选项 |文本编辑器 | C＃。对应的 EditorBrowsableState 为 Advanced。

【讨论】：

【解决方案3】：

沟通缺乏支持的一部分是不提供任何支持 XML 形式的智能感知厘米。

你能用一个简单的

Not for external use.

评论来评论这些方法吗？

【讨论】：

【解决方案4】：

尝试将#pragma 指令用于enable or disable specific warnings。

///<summary>some documentation</summary>
public class A{
    //...
}

#pragma warning disable 1591
public class B{
    //...
}

【讨论】：