visual una studio librerias hacer generar documentar documentacion crear como codigo clases clase biblioteca c# vb.net visual-studio documentation

c# - una - La mejor manera de agregar documentación de desarrollador a tus proyectos de Visual Studio



generar documentacion visual studio 2017 (4)

En los comentarios de XML, tiene la opción de incluir una gran cantidad de datos que luego puede retomar con una herramienta como Sandcastle (site) y convertirse en un sitio de referencia real al estilo de MSDN.

Tiendo a usar este método y simplemente escribo largos comentarios XML (etiquetas de comentarios de MSDN) (cuando sea apropiado) usando el <para></para> para generar párrafos y explicar cualquier patrón, razón comercial o información arquitectónica necesaria para futuros modificadores / desarrolladores. También lo uso para dar ejemplos de uso.

Un buen lote de pruebas (bien escrito y nombrado) también puede iluminar realmente el propósito del código, actuando como una especificación.

Espero que sea un poco informativo en tu investigación :)

Básicamente, la pregunta es: ¿Dónde (y en qué formato) debo almacenar la documentación textual del desarrollador asociada a mis proyectos de Visual Studio?

Para elaborar: los comentarios XML son geniales, pero no cubren todos los casos de uso. A veces, le gustaría describir la arquitectura de clase del proyecto en un nivel alto, agregar notas de uso a su biblioteca o simplemente dejar cualquier otro tipo de mensaje a las generaciones futuras de desarrolladores que trabajan en este proyecto.

Me gustaría agregar estos documentos directamente como archivos en el proyecto de Visual Studio, para asegurar (a) que estén disponibles para el desarrollador sin más búsquedas y (b) que estén controlados por la versión (usando el mismo repositorio svn / git / whatever como el código fuente).

Actualmente, agrego una carpeta _Documentation al proyecto y uso archivos de texto, pero no estoy seguro de si esta es la mejor solución. Visual Studio no tiene una opción para el texto 1 de ajuste automático de palabra, y la fijación manual de saltos de línea después de cada cambio es molesto. Por otro lado, los documentos de Word no funcionan bien con el control de versiones, y TeX es demasiado complicado de configurar y enseñar en cada PC de desarrollo.

¿Existe una mejor práctica bien establecida para esto?

1 Sé que hay Edit / Advanced / Word-Wrap, pero esto solo afecta a la pantalla, no al archivo en sí.

Los Comentarios XML son los mejores para documentar el método particular y no son ideales para escribir contenido conceptual largo. Los comentarios XML largos podrían afectar negativamente la legibilidad del código.

Me gustó la función de documentación conceptual temática de Sandcastle, podemos crear y almacenar documentación conceptual ya sea funcional o relacionada con la arquitectura y fusionarla con la documentación del Código (Comentarios XML). Las marcas que puede utilizar para escribir los temas conceptuales son extensibles, lo que significa que incluso podemos adherirnos a las plantillas de Enterprise.

Solo tuve el mismo problema, solo me di cuenta de que podía agregar un archivo HTML. Una vez abierto, simplemente cambie a "Diseño" en la parte inferior de la pantalla. Es posible que desee cambiar Build Action de ''Contenido'' a ''Ninguno''

Como es un documento HTML codificado, también es posible usar imágenes en línea (por ejemplo, un diagrama)

También para mi propósito (guía de programación, descripción de la arquitectura, ejemplos de uso de la base de datos) Opté por crear un proyecto separado ( _Documentation ) como Formularios de Windows , ya que esto me permitirá (o un programador nuevo) tener un ejemplo en ejecución.