Documentos .NET xml: heredar documentación

Question

NDoc tiene un elemento XML heredadodoc 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 comprende esta etiqueta y se queja de que la documentación no está presente o completa. También StyleCop y algunas otras herramientas. ¿Hay un enfoque alternativo? ¿Cómo haces 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 ti Por supuesto, esto duplica la descripción XML, que es parte de lo que está tratando de evitar, pero al menos lo hace automáticamente por usted.

¿Qué sucede si solo dejas los documentos por completo para los métodos que se heredan o anulan 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 quejará cuando no produzca documentos para un método heredado. Vale la pena intentarlo, sin duda.

Answer 2

Tengo una mejor respuesta: FiXml .

Clonar comentarios con GhostDoc es ciertamente un enfoque funcional, 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ás produciendo una gran cantidad de duplicados. Si estás usando alguna herramientas de análisis de código fuente (por ejemplo, Buscador duplicado en Team City), lo hará encuentra principalmente tus comentarios.

Breve descripción de FiXml: es un postprocesador de documentación XML producida 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 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 & # 8217; es bastante deseable heredar al menos parte de ella.
• No se admite la inserción de plantillas de documentación de uso común , como & # 8220; este tipo es singleton: use su propiedad <see cref="Instance" /> para obtener la única instancia de la misma. & # 8221 ;, o incluso & # 8220; Inicializa una nueva instancia de <CurrentType> clase. & # 8221;

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

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

Aquí está su página web y página de descarga (enlaces rotos).

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

• Sandcastle produce archivos de ayuda HTML compilados, no modifica .xml archivos que contiene comentarios XML extraídos. Pero estos archivos son utilizados por muchas herramientas, incluyendo .NET Reflector y clase browser \ 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. P.ej. el es no <see ... copy="true" />.

Ver Descripción <=> de Sandcastle para más detalles.

Answer 3

Creé una herramienta de línea de comando para procesar posteriormente los archivos de documentación XML para agregar soporte para < inheritdoc / > etiqueta.

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

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