Realización de reglas e interfaces de StyleCop SA1600

Question

Regla StyleCop SA1600 exige que cada miembro del tipo tenga su propio encabezado de documentación. Creo que es bastante razonable y me gusta esta regla. Pero supongamos que tenemos la siguiente jerarquía:

/// <summary> 
/// Documentation for interface ISomeModule. 
/// </summary> 
interface ISomeModule 
{ 
    /// <summary> 
    /// Documentation for DoA. 
    /// </summary> 
    void DoA(); 

    /// <summary> 
    /// Documentation for DoB. 
    /// </summary> 
    void DoB(); 
} 

/// <summary> 
/// Documentation for StandardModule. 
/// </summary> 
class StandardModule : ISomeModule 
{ 
    private readonly SomeCoolType _value; 

    /// <summary> 
    /// Documentation for constructor. 
    /// </summary> 
    public StandardModule(SomeCoolType value) 
    { 
     _value = value; 
    } 

    // SA1600 violation here! 
    public void DoA() 
    { 
     // realisation of DoA(). 
    } 

    // SA1600 violation here! 
    public void DoB() 
    { 
     // realisation of DoB(). 
    } 

    /// <summary> 
    /// Documentation for MyOwnDoC. 
    /// </summary> 
    public void MyOwnDoC() 
    { 
     // realisation of MyOwnDoC(). 
    } 
} 

aquí, elementos de interfaz totalmente documentados DOA() y fecha de nacimiento(), que saben lo que estos métodos hacen exactamente de la documentación de la interfaz. VS Intellisence también lo sabe y podemos ver la descripción de los métodos colocando el mouse sobre estos métodos incluso en la clase StandardModule. Por lo tanto, no es necesario copiar la documentación de la interfaz a la clase derivada. Pero StyleCop exige hacerlo. ¿Por qué? ¿Alguien sabe?

Si tratamos de resolver este problema, podemos ir 4 formas diferentes: la documentación

1. Copia de la interfaz. El problema aquí es que si copiamos la documentación resolveremos el problema de actualizar la documentación en todas las clases derivadas si el comportamiento de la interfaz cambia.

2. Suprima el mensaje con SuppressMessageAttribute. Bueno, supongamos que decimos "Ok, puedo usar SuppressMessageAttribute" para suprimir esta violación con la que no estoy de acuerdo. Y antepongo la clase StandardModule con SuppressMessageAttribute para la regla SA1600. Pero ahora StyleCop deja de buscar encabezados de documentación en la clase StandardModule en absoluto. No lo quiero, porque tenemos constructor y algunos otros métodos.

3. Divida la clase en regiones, podemos dividir StandardModule clase en 2 regiones y el uso de la eliminación de mensajes sólo en la parte que implementa la interfaz ISomeModule. Y creo que todas las partes deben colocarse en un solo archivo. Me gusta este enfoque sobre todo (después del camino # 4), pero ahora tenemos que tratar con múltiples partes de una clase.

4. Modifique la regla SA1600. ¿Es posible realizar mi propia implementación de la regla SA1600 de manera que tenga en cuenta si los miembros de la clase se documentaron en una clase base o en una interfaz? (Aquí no pregunto si podemos escribir nuestra propia regla para StyleCop, sé que podemos, pero me refiero a si el motor de StyleCop puede verificar si algunos miembros provienen de la interfaz o la clase base).

¿Cuál es la forma más preferible de resolver el problema SA1600 en la realización de la interfaz?

Answer 1

La próxima versión de StyleCop 4.4.1 se supone que admite la etiqueta inheritdoc. Si está dispuesto a utilizar una herramienta de generación de documentación que admita esta etiqueta (por ejemplo, Sandcastle o FiXml), es posible que tenga una solución de trabajo que aborde sus dos inquietudes.

Answer 2

Nunca me ocurrió que esto sería un problema porque siempre consideré la documentación de la declaración de una interfaz como algo diferente de la documentación de la aplicación de esta interfaz.

Puedo estar equivocado pero estoy feliz de aprender.

Mi respuesta real a su pregunta sería: 1) Copiar Traducir la documentación de la interfaz.