Selectively suppress comments on XML in C #?

Question

We supply a number of builds to external clients, but not all official APIs are officially supported. For example, because of less optimal design options, sometimes a type must be publicly displayed on the assembly for the rest of our code to work, but we do not want clients to use this type. One part of the lack of support message does not provide any intellisense as XML comments.

Is there a way to selectively suppress XML comments? I am looking for something else besides ignoring warning 1591, as this is a long term maintenance issue.

Example. I have an assembly with the public classes A and B. A is officially supported and has XML documentation. B is not intended for external use and should not be documented. I could turn on the 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 messed up and was unable to add the XML documentation. This would not happen if I crushed 1591 at the project level. I suppose I could be a pragma for all classes, but it seems like there should be a better way to do this.

Answer 1

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

That way you can still document unsupported classes (internal users are also important!) And your external users don't see them in intellisense. Inside, you can let the visual studio “see” these advanced designs. The EditorBrowsableAttribute page tells us how:

In Visual C #, you can control when advanced properties appear in IntelliSense and the properties window with the Hide Advanced Members option in the Tools | Options | Text editor | FROM#. The corresponding EditorBrowsableState is advanced.

Answer 2

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

Answer 3

One part of the lack of support message does not provide any intellisense as XML comments.

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

Answer 4

Try using the #pragma to enable or disable certain warnings .

 ///<summary>some documentation</summary> public class A{ //... } #pragma warning disable 1591 public class B{ //... }