what - .NET xml docs-herencia de documentación

which example is a valid visual c# xml documentation comment

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 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 simplemente dejas los documentos por completo para los métodos que se heredan, o si anulas 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 mejor respuesta: FiXml .

La clonación de comentarios con GhostDoc es ciertamente un enfoque de trabajo, 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.

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

Finalmente, hay <inheritdoc> etiqueta <inheritdoc> en Sandcastle : definitivamente es mejor usarla que copiar comentarios XML, pero tiene algunas desventajas en comparación con FiXml:

• Sandcastle produce archivos compilados de ayuda HTML; no modifica los archivos .xml que contienen comentarios XML extraídos. Pero muchas herramientas utilizan estos archivos, como .NET Reflector y el explorador de clases / IntelliSense en Visual Studio .NET. Entonces, si usa solo Sandcastle, no verá la documentación heredada allí.
• La implementación de Sandcastle es menos poderosa. Por ejemplo, el no es <see ... copy="true" /> .

Ver la descripción <inheritdoc> Sandcastle para más detalles.