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

98

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

Valentin Vasilyev
fuente
¿Está implementada esta función? visualstudio.uservoice.com/forums/121579-visual-studio/...
Hellboy
¿Cómo puedo hacer que Atomineer Pro permita generar la etiqueta de documentación <hereitDoc /> para la implementación si la documentación para la interfaz está disponible?
hellboy
3
Tienes razón <inheritdoc/>está roto en Visual Studio. Vote por el informe de error en visualstudio.uservoice.com/forums/121579-visual-studio/…
Colonel Panic

Respuestas:

62

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

Noldorin
fuente
¡Oye, eso está muy bien! ¡Me gusta Sandcastle!
Tor Haugen
Publicación editada para responder a la pregunta actualizada.
Noldorin
2
¿Se puede hacer esto a nivel de clase? para que no tenga que poner /// <hereitdoc /> antes de cada método.
Antony Scott
1
Una cosa que he notado es que <inheritdoc/> no hereda la documentación de la <param>etiqueta.
Stephen
1
Sube-votar esta característica voz del usuario para tener <inheritdoc /> agregó oficialmente a la especificación de C # y el trabajo, con el VS intelisense visualstudio.uservoice.com/forums/121579-visual-studio/...
deadlydog
14

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

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.

Igal Tabachnik
fuente
La versión más reciente (5.3.16270) de GhostDoc también puede crear documentos heredados. Lo acabo de probar para mis implementaciones de interfaz. Bonito bono, también agrega las excepciones con el mensaje de la excepción lanzada :-)
Christoph
6

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.

Stefan Steinegger
fuente
4

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

Tor Haugen
fuente
6
Personalmente, no me gusta GhostDoc. Genera documentación donde en realidad no hay ninguna. Esto esconde el hecho de que algo no está documentado. Solo una opinión personal, no digo que sea algo malo en general.
Stefan Steinegger
1
De acuerdo con el comentario de Stefan en cuanto a que GhostDoc no es perfecto, sin embargo, automáticamente genera comentarios "heredados" como este, por lo que es una respuesta bastante buena a la pregunta.
Steve
Stefan, no estoy de acuerdo; por el contrario, porque GhostDoc solo refleja la documentación que ya "pusiste" en los nombres de tus miembros (construyendo prosa a partir de los nombres), solo genera documentación donde la documentación ya existe (implícitamente). Como tal, no "produce" nada, pero la prosa generada es un excelente punto de partida al que puede agregar valor real. La documentación real todavía requiere algo de trabajo.
Tor Haugen
2

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 .

Alex Yakunin
fuente
1

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

K Johnson
fuente
0

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.

1800 INFORMACIÓN
fuente
3
No habría usado la interfaz aquí si no la hubiera estado fingiendo en las pruebas.
Valentin Vasilyev
0

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

crauscher
fuente