suprimir selectivamente los comentarios del código XML en C#?

Question

Entregamos una serie de ensamblajes a clientes externos, pero no todas las API públicas son oficialmente compatibles. Por ejemplo, debido a opciones de diseño menos que óptimas, a veces un tipo debe exponerse públicamente desde un ensamblaje para que funcione el resto de nuestro código, pero no queremos que los clientes usen ese tipo. Una parte de comunicar la falta de soporte no es proporcionar ningún tipo de inteligencia en forma de comentarios XML.

¿Hay alguna forma de suprimir selectivamente los comentarios XML? Estoy buscando algo más que ignorar la advertencia 1591 ya que es un problema de mantenimiento a largo plazo.

Ejemplo: Tengo un ensamblado con las clases públicas A y B. A es oficialmente compatible y debe tener documentación XML. B no es para uso externo y no debe documentarse. Podría activar la documentación XML y luego suprimir la advertencia 1591. Pero cuando más tarde agregue la clase C oficialmente admitida, quiero que el compilador me diga que me equivoqué y no pude agregar la documentación XML. Esto no ocurriría si hubiera suprimido 1591 a nivel de proyecto. Supongo que podría #pragma en todas las clases, pero parece que debería haber una mejor manera de hacerlo.

Answer 1

¿Qué le parece no proporcionar intellisense en absoluto?

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

De esta manera, todavía se puede documentar clases sin apoyo (usuarios internos también son importantes!) Y tienen sus usuarios externos no verlos en IntelliSense. Internamente, puede habilitar Visual Studio para "ver" estos constructos avanzados. La página para el EditorBrowsableAttribute nos dice cómo:

En Visual C#, puede controlar cuando las propiedades avanzadas aparecen en IntelliSense y la ventana de propiedades con la configuración Ocultar miembros avanzados en Herramientas | Opciones | Editor de texto | DO#. El EditorBrowsableState correspondiente es Avanzado.

Answer 2

Realice dichos métodos internal y agregue el atributo [assembly: InternalsVisibleTo("AssemblyName")] al ensamblaje exponiéndolos.

Answer 3

Intente utilizar la directiva #pragma en enable or disable specific warnings.

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

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

Answer 4

Una parte de la comunicación de la falta de apoyo no se proporcionará ninguna intelisense en forma de XML comentarios.

Podría en cambio comentar estos métodos con un simple resumen > < No es para uso externo. </summary > comentario?