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

Question

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

ACTUALIZACIÓN:

consideran este código:

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

Cuando creo clase como esta:

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

Aquí comentarios no se muestran:

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

ElLa etiquetagenerará perfectamente la documentación en Sand Castle, pero no funciona en la información de herramientas de intellisense.

Por favor comparta sus ideas.

Gracias.

Answer 1

Puede hacerlo fácilmente usando la etiqueta Microsoft Sandcastle (o NDoc) inheritdoc. La especificación no lo admite oficialmente, pero las etiquetas personalizadas son perfectamente aceptables y, de hecho, Microsoft optó por 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) 
{ 
    // 
} 

Here es la página de ayuda desde el castillo de arena Archivo de Ayuda Constructor de GUI, que describe su uso en su totalidad.

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

Como nota, esto suena como una Es una idea perfectamente justa para mí, aunque he observado que algunas personas piensan que siempre debes volver a especificar los comentarios en las clases derivadas e implementadas. (De hecho, yo mismo lo hice documentando una de mis bibliotecas y no he visto ningún problema). Casi nunca hay razón para que los comentarios difieran en absoluto, así que ¿por qué no heredar y hacerlo de la manera fácil?

Edit: 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 utiliza para la entrada, lo que significa que puede distribuir esta versión modificada junto con su DLL de biblioteca en lugar de la compilada directamente por Visual Studio, lo que significa que tiene los comentarios en intellisense como así como el archivo de documentación (CHM, lo que sea)

Answer 2

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

Answer 3

suelo escribir comentarios como éste:

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

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

Editar:

Si desea ver documentos cuando se llama a la clase directamente y no usando la interfaz, tiene que escribir dos veces o utilizar una herramienta como GhostDoc.

Answer 4

Probar GhostDoc! Funciona para mí :-)

Editar: Ahora que he tenido conocimiento de apoyo de castillo de arena para <inheritdoc/>, estoy de acuerdo con el post de Noldorin. Es una solución mucho mejor. Aun así, recomiendo GhostDoc de forma general.

Answer 5

Si no lo está usando ya, le recomiendo un complemento gratuito de Visual Studio llamado GhostDoc. Facilita el proceso de documentación. Eche un vistazo a my comment en una pregunta algo relacionada.

Aunque GhostDoc no hará que la sincronización automática, que le puede ayudar 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.

Ir a los Opciones -> Teclado ajustes, y asignar una clave a GhostDoc.AddIn.RebuildDocumentation (utilicé Ctrl-Shift-Alt-D). alt text http://i44.tinypic.com/10dd1f9.png

Ahora, si cambia el comentario de XML en la interfaz, sólo tiene que pulsar esta tecla de acceso directo en el método implementado, y la documentación se actualizará. Lamentablemente, esto no funciona al revés.

Answer 6

/// <inheritDoc/> 

Read here

Use this

Answer 7

Con ReSharper se puede copiar, pero no creo que esté sincronizado todo el tiempo.

Answer 8

Tengo una respuesta mejor: FiXml.

Clonación del enfoque de trabajo es, sin duda, pero tiene desventajas significativas, por ejemplo .:

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

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

• castillo de arena produce archivos de ayuda HTML compilados - normalmente no modifica .xml archivos 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. P.ej. el no es <see ... copy="true" />.

Consulte Sandcastle's <inheritdoc> description para obtener más información.

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

• No hay soporte para heredar la documentación de la clase base o interfaz. Es decir una documentación para cualquier miembro anulado se debe escribir desde cero, aunque normalmente es bastante deseable heredar al menos una parte de ella.
• No hay soporte para la inserción de plantillas de documentación de uso común, tales como “Este tipo es Singleton -. Utilizar su propiedad <see cref="Instance" /> para conseguir la única instancia de ella”, 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="..." /> attrib ute en la etiqueta <see/>.

Aquí está its web page y download page.

Answer 9

Creé una biblioteca para procesar los archivos de documentación XML para agregar compatibilidad con la etiqueta < inheritdoc/>.

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 los paquetes NuGet a los que se hace referencia.

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