valid - Formas de sincronizar los comentarios de interfaz e implementación en C#

summary c# documentation

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.

ACTUALIZAR:

Considera 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í los comentarios no se muestran:

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

La <inheritDoc/> generará perfectamente la documentación en Sand Castle, pero no funciona en IntelliSense tooltips.

Por favor comparte tus ideas.

Gracias.

Answer 1

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

Answer 2

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).

Answer 3

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 4

Normalmente escribo comentarios como este:

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

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

Editar:

Si desea ver documentos cuando llama a la clase directamente y no utiliza la interfaz, debe escribirla dos veces o utilizar una herramienta como GhostDoc.

Answer 5

Prueba GhostDoc ! Esto funciona para mi :-)

Editar: Ahora que conozco el soporte de Sandcastle para <inheritdoc/> , respaldo la publicación de Noldorin. Es una solución mucho mejor. Aun así, recomiendo GhostDoc de forma general.

Answer 6

Puede hacerlo fácilmente usando la etiqueta inheritdoc Microsoft Sandcastle (o NDoc). 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 está la página de ayuda de Sandcastle Help File Builder GUI, que describe su uso completo.

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

Como nota, esto me parece una idea perfectamente justa, 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?

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

Answer 7

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 mi comentario sobre una pregunta algo relacionada.

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

Tienes 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 clave a GhostDoc.AddIn.RebuildDocumentation (utilicé Ctrl-Shift-Alt-D ). texto alternativo http://i44.tinypic.com/10dd1f9.png

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

Answer 8

Tengo una mejor respuesta: FiXml .

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

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

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

• Sandcastle produce archivos compilados de ayuda HTML, normalmente no modifica los archivos .xml 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 no es <see ... copy="true" /> .

Ver Here para más detalles.

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 estos idiomas:

• No admite la herencia de la documentación de la clase base o la 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 admite la inserción de plantillas de documentación comúnmente utilizadas , como "Este tipo es singleton: use su <see cref="Instance" /> para obtener la única instancia de este.", O incluso "Inicializa una nueva instancia de <CurrentType> clase. "

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

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

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

Answer 9

/// <inheritDoc/>

Leer aquí

Utilizar esta