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

Question

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

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

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

Answer 1

制作这样的方法internal，并将[assembly: InternalsVisibleTo("AssemblyName")]属性添加到公开它们的程序集中。

Answer 2

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

你能用一个简单的<summary>Not for external use.</summary>评论来评论这些方法吗？

Answer 3

根本不提供智能感知怎么样？

///<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。

Answer 4

尝试使用该#pragma指令启用或禁用特定警告。

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

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