Formas de sincronizar los comentarios de la interfaz y la implementación en C # [cerrado]

¿Existen formas automáticas de sincronizar comentarios entre una interfaz y su implementación? Actualmente los estoy documentando a ambos y no me gustaría mantenerlos sincronizados manualmente.

ACTUALIZAR:

Considere este código:

interface IFoo{
    /// <summary>
    /// Commenting DoThis method
    /// </summary>
    void DoThis();
}
class Foo : IFoo {
    public void DoThis();
}

Cuando creo una clase como esta:

IFoo foo=new Foo();
foo.DoThis();//comments are shown in intellisense

Aquí no se muestran los comentarios:

Foo foo=new Foo();
foo.DoThis();//comments are not shown in intellisense

La <inheritDoc/>etiqueta generará perfectamente la documentación en Sand Castle, pero no funciona en la información sobre herramientas de intellisense.

Comparta sus ideas.

Gracias.

Puede hacer esto con bastante facilidad utilizando la inheritdocetiqueta Microsoft Sandcastle (o NDoc) . La especificación no lo admite oficialmente, pero las etiquetas personalizadas son perfectamente aceptables y, de hecho, Microsoft eligió copiar esta (y una o dos etiquetas más) de NDoc cuando crearon Sandcastle.

/// <inheritdoc/>
/// <remarks>
/// You can still specify all the normal XML tags here, and they will
/// overwrite inherited ones accordingly.
/// </remarks>
public void MethodImplementingInterfaceMethod(string foo, int bar)
{
    //
}

Aquí está la página de ayuda de la GUI de Sandcastle Help File Builder, que describe su uso en su totalidad.

(Por supuesto, esto no es específicamente "sincronización", como menciona su pregunta, pero parece ser exactamente lo que está buscando).

Como nota, esto me parece una idea perfectamente justa, aunque he observado que algunas personas piensan que siempre se deben respetar los comentarios en las clases derivadas e implementadas. (De hecho, lo hice yo mismo al documentar una de mis bibliotecas y no he visto ningún problema en absoluto). Casi siempre no hay razón para que los comentarios difieran en absoluto, así que ¿por qué no simplemente heredar y hacerlo de la manera más fácil?

Editar: Con respecto a su actualización, Sandcastle también puede encargarse de eso por usted. Sandcastle puede generar una versión modificada del archivo XML real que usa para la entrada, lo que significa que puede distribuir esta versión modificada junto con la DLL de su biblioteca en lugar de la creada directamente por Visual Studio, lo que significa que tiene los comentarios en intellisense así como el archivo de documentación (CHM, lo que sea).

Si aún no lo está utilizando, le recomiendo encarecidamente un complemento de Visual Studio gratuito llamado GhostDoc . Facilita el proceso de documentación. Eche un vistazo a mi comentario sobre una pregunta relacionada.

Aunque GhostDoc no realizará la sincronización automáticamente, puede ayudarlo con el siguiente escenario:

Tiene un método de interfaz documentado. Implemente esta interfaz en una clase, presione la tecla de acceso directo GhostDoc Ctrl-Shift-D, y el comentario XML de la interfaz se agregará al método implementado.

Vaya a Opciones -> Configuración del teclado y asigne una tecla a GhostDoc.AddIn.RebuildDocumentation(Yo usé Ctrl-Shift-Alt-D).

Ahora, si cambia el comentario XML en la interfaz , simplemente presione esta tecla de método abreviado en el método implementado y la documentación se actualizará. Desafortunadamente, esto no funciona al revés.

Normalmente escribo comentarios como este:

/// <summary>
/// Implements <see cref="IMyInterface.Foo(string, int)"/>
/// </summary>
/// <returns></returns>

Los métodos son utilizados solo por la interfaz, por lo que este comentario ni siquiera se muestra en la información sobre herramientas al codificar.

Editar:

Si desea ver los documentos cuando llama a la clase directamente y no usa la interfaz, debe escribirlos dos veces o usar una herramienta como GhostDoc.

¡Prueba GhostDoc ! Esto funciona para mi :-)

Editar: Ahora que me he enterado del apoyo de Sandcastle, apoyo <inheritdoc/>la publicación de Noldorin. Es una solución mucho mejor. Sin embargo, todavía recomiendo GhostDoc de forma general.

Tengo una mejor respuesta: FiXml . Soy uno de sus autores

La clonación del enfoque es ciertamente funcional, pero tiene desventajas significativas, por ejemplo:

• Cuando se cambia el comentario original (lo que ocurre con frecuencia durante el desarrollo), su clon no.
• Estás produciendo una gran cantidad de duplicados. Si está utilizando alguna herramienta de análisis de código fuente (por ejemplo, Duplicate Finder en Team City), encontrará principalmente sus comentarios.

Como se mencionó, hay una <inheritdoc>etiqueta en Sandcastle , pero tiene algunas desventajas en comparación con FiXml:

• Sandcastle produce archivos de ayuda HTML compilados, normalmente no modifica .xmlarchivos que contienen comentarios XML extraídos (por último, esto no se puede hacer "sobre la marcha" durante la compilación).
• La implementación de Sandcastle es menos poderosa. Por ejemplo, el es no <see ... copy="true" />.

Consulte la <inheritdoc>descripción de Sandcastle para obtener más detalles.

Breve descripción de FiXml: es un posprocesador de documentación XML producido por C # \ Visual Basic .Net. Se implementa como tarea de MSBuild, por lo que es bastante fácil integrarlo a cualquier proyecto. Aborda algunos casos molestos relacionados con la escritura de documentación XML en estos lenguajes:

• No hay soporte para heredar la documentación de la clase base o interfaz. Es decir, una documentación para cualquier miembro anulado debe escribirse desde cero, aunque normalmente es bastante deseable heredar al menos una parte.
• No se admite la inserción de plantillas de documentación de uso común , como "Este tipo es singleton: use su <see cref="Instance" />propiedad para obtener la única instancia de él", o incluso "Inicializa una nueva instancia de <CurrentType>clase".

Para resolver los problemas mencionados, se proporcionan las siguientes etiquetas XML adicionales:

• <inheritdoc />, <inherited /> etiquetas
• <see cref="..." copy="..." />atributo en la <see/>etiqueta.

Aquí está su página web y página de descarga .

/// <inheritDoc/>

Leer aquí

Utilizar este

Creé una biblioteca para posprocesar los archivos de documentación XML para agregar soporte para la etiqueta <hereitdoc />.

Si bien no ayuda con Intellisense en el código fuente, sí permite que los archivos de documentación XML modificados se incluyan en un paquete NuGet y, por lo tanto, funciona con Intellisense en paquetes NuGet referenciados.

Más información en www.inheritdoc.io (versión gratuita disponible).

No hagas eso. Piénselo de esta manera: si se requiere que ambos comentarios sean iguales todo el tiempo, entonces uno de ellos no es necesario. Tiene que haber una razón para el comentario (además de algún tipo de obligación extraña de bloquear el comentario de cada función y variable), por lo que debe averiguar cuál es esa razón única y documentarla.

Con ReSharper puedes copiarlo, pero no creo que esté sincronizado todo el tiempo.