.NET xml docs - herencia de documentación

Question

NDoc tiene un elemento XML inheritdoc que le permite heredar la documentación de un miembro de la clase principal (o una interfaz implementada). Sin embargo, Visual Studio (es decir, el compilador de C#) no entiende esta etiqueta y se queja de que la documentación no está presente o completa. Lo mismo ocurre con StyleCop y algunas otras herramientas. ¿Hay un enfoque alternativo? ¿Cómo se hace para mantener los documentos completos, pero sin duplicar las descripciones XML?

Answer 1

Una alternativa es usar GhostDoc - un complemento para Visual Studio que genera automáticamente comentarios para usted. Esto duplica la descripción XML, por supuesto, que es parte de lo que intenta evitar, pero al menos lo hace automáticamente.

¿Qué sucede si solo deja los documentos por completo para los métodos que se heredan, o para reemplazar los métodos de interfaz? Sospecho que depende de cómo haya configurado NDoc, pero ciertamente en la documentación de MSDN parece heredar naturalmente los documentos, y una comprobación rápida sugiere que VS no se moverá cuando no produzca documentos para un método heredado. . Vale la pena intentarlo, sin duda.

Answer 2

Tengo una respuesta mejor: FiXml.

clonación comentarios con GhostDoc enfoque es, sin duda trabajan, 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.

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 (enlaces rotos).

Por último, hay <inheritdoc> etiqueta en Sandcastle - es definitivamente mejor usarlo de copiar los comentarios XML, pero tiene algunas desventajas en comparación con FIXML:

• castillo de arena produce archivos de ayuda HTML compilados - no modifica los archivos .xml que contienen comentarios XML extraídos. Sin embargo, estas herramientas son utilizadas por muchas herramientas, , que incluyen .NET Reflector y el explorador de clases \ IntelliSense en Visual Studio .NET. Si solo usa Sandcastle, no verá la documentación heredada allí.
• 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.

Answer 3

Creé una herramienta de línea de comandos para procesar los archivos de documentación XML para agregar compatibilidad con la etiqueta < inheritdoc/>.

No ayuda con Intellisense en el código fuente, pero 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.

Consulte www.inheritdoc.io para obtener más información (versión gratuita disponible).