XML Documentation Comments with Interfaces and implementation class (es)

Question

Estoy documentando un ensamblaje usando XML Documentation Comments, del cual se creará un archivo chm usando Sandcastle.

Mi ensamblaje contiene varias interfaces, cada una de las cuales se implementa mediante una clase (en mi escenario se trata de servicios WCF).

He añadido la documentación de las interfaces, ¿hay alguna manera para mí de documento de forma automática los métodos pertinentes sobre las clases que implementan?

Answer 1

Parece no haber ningún apoyo para tal autodocumentation en castillo de arena. El Sandcastle Help File Builder aunque implementa una etiqueta inheritdoc personalizada.

Desde el sitio SHFB:

Se incluye soporte para la etiqueta >/ < inheritdoc que le permite documentación hereda desde la base Típicos/miembros. Esto se implementa a través de una herramienta independiente por lo que también puede ser utilizado por otras herramientas de terceros y scripts de construcción. Esta herramienta proporciona las características más allá de las que se encuentran en el componente de construcción suministrado con Sandcastle.

Segundo informe de actualización: acuerdo con this workitem, el "apoyo" Castillo de arena para inheritdoc es a través de la herramienta SHFB. En pocas palabras, supongo que es, SHFB resuelve su problema.

Answer 2

Una herramienta como GhostDoc puede generar la documentación sobre las clases de ejecución, cuando se utiliza en este acceso directo del teclado. Eso no es completamente automático, pero podría ayudar a evitar el exceso de copiado.

Quizás se podría automized con un guión.

Answer 3

AtomineerUtils generará automáticamente comentarios para usted, y recoge la documentación existente de sobrecargas y reemplazó la clase base, ahorrándole muchas molestias al duplicar la información donde sea necesaria.

http://www.atomineer.com/AtomineerUtils.html

Answer 4

que tienen una mejor respuesta: FIXML.

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

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

• castillo de arena produce archivos de ayuda HTML compilado - no modifica archivos .xml que contiene 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.

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.