La mejor manera de agregar documentación de desarrollador a sus proyectos de Visual Studio

Question

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

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 realizar búsquedas adicionales y (b) están controlados por la versión (usando el mismo svn/git/cualquier repositorio 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 texto 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 buena práctica establecida para esto?

---

sé que hay Editar/Avanzado/Palabra-Wrap, pero esto sólo afecta a la pantalla, no el propio archivo.

Answer 1

Acabo de tener el mismo problema, solo noté 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 Acción de generación de 'contenido' a 'Ninguno'

Como se trata de un documento HTML no modificable, también es posible utilizar en línea imágenes (por ejemplo, un diagrama)

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

Answer 2

utilizo GhostDoc (Visual Studio add-on) para la documentación de mi proyecto como agrego clases, métodos, propiedades, etc: http://visualstudiogallery.msdn.microsoft.com/46A20578-F0D5-4B1E-B55D-F001A6345748

Answer 3

Usted tiene la opción, en los comentarios XML, para incluir una gran cantidad de datos que A continuación, puede elegir una herramienta como Sandcastle (site) y convertirse en un sitio de referencia real de MSDN.

Tiendo a utilizar este método y simplemente escribo largos comentarios XML (MSDN comment tags) (según corresponda) 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 realmente iluminar el propósito del código, actuando como una especificación.

espero que podría ser un poco informativo en su investigación :)

Answer 4

XML comentarios es el mejor para documentar el método particular y no es ideal para la escritura de contenido conceptual de 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.