Selectively suppress XML Code Comments in C#?

Question

We deliver a number of assemblies to external customers, but not all of the public APIs are officially supported. For example, due to less than optimal design choices sometimes a type must be publicly exposed from an assembly for the rest of our code to work, but we don't want customers to use that type. One part of communicating the lack of support is not provide any intellisense in the form of XML comments.

Is there a way to selectively suppress XML comments? I'm looking for something other than ignoring warning 1591 since it's a long term maintenance issue.

Example: I have an assembly with public classes A and B. A is officially supported and should have XML documentation. B is not intended for external use and should not be documented. I could turn on XML documentation and then suppress warning 1591. But when I later add the officially supported class C, I want the compiler to tell me that I've screwed up and failed to add the XML documentation. This wouldn't occur if I had suppressed 1591 at the project level. I suppose I could #pragma across entire classes, but it seems like there should be a better way to do this.

Answer 1

Make such methods internal, and add the [assembly: InternalsVisibleTo("AssemblyName")] attribute to the assembly exposing them.

Answer 2

How about not providing intellisense at all?

///<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 { }

This way, you can still document unsupported classes (internal users are also important!) and have your external users not see them on intellisense. Internally, you can enable visual studio to "see" these advanced constructs. The page for the EditorBrowsableAttribute tells us how:

In Visual C#, you can control when advanced properties appear in IntelliSense and the Properties Window with the Hide Advanced Members setting under Tools | Options | Text Editor | C#. The corresponding EditorBrowsableState is Advanced.

Answer 3

One part of communicating the lack of support is not provide any intellisense in the form of XML comments.

Could you instead comment these methods with a simple <summary>Not for external use.</summary> comment?