Autodocumentación .NET: XMLDoc+GhostDoc+Sandcastle
Sin documentación, el software nace, crece, se vuelve spaghetti, desquicia a los developers y todos mueren.
Aquí una guía súper rápida para que la documentación no sea un pain, y además tener el motivador de que al final vamos a poder tener páginas de documentación estilo MSDN, usando la última versión de Visual Studio: la 2012.
Ingredientes:
- Visual Studio 2012
- No necesita presentación
- Ghost Doc
- Es una extensión para Visual Studio que genera comentarios de documentación XML automáticamente para métodos y propiedades, basándose en su tipo, parámetros, nombre y otra información contextual. Es un addin que además desinstala automáticamente versiones anteriores y las actualize con las nuevas que estemos instalando.
- Sandcastle Help File Builder
- Sandcastle es una herramienta creada por Microsoft y publicada Open Source en Codeplex para crear documentación Estilo MSD basándose en los assemblies .NET y sus comentarios XML asociados. Es un tool basado en línea de comandos y no tiene una GUI pre-definida. Así que la curva de aprendizaje es alta. Afortunadamente la aplicación Sandcastle Help Builder ha sido construida sobre Sandcastle para proveer un fácil manejo de todas las opciones que tiene Sandcastle, de tal manera que el uso sea parecido al del antiguo NDoc.
La instalación de esta aplicación requiere varios paquetes preinstalados y configurados. Por eso viene con un wizard bastante amigable que ayuda a la configuración.
- Sandcastle es una herramienta creada por Microsoft y publicada Open Source en Codeplex para crear documentación Estilo MSD basándose en los assemblies .NET y sus comentarios XML asociados. Es un tool basado en línea de comandos y no tiene una GUI pre-definida. Así que la curva de aprendizaje es alta. Afortunadamente la aplicación Sandcastle Help Builder ha sido construida sobre Sandcastle para proveer un fácil manejo de todas las opciones que tiene Sandcastle, de tal manera que el uso sea parecido al del antiguo NDoc.
Una vez tenemos todo instalado, pasemos a observar cómo generar la documentación!
Comments
Anonymous
August 24, 2012
Excelente una pregunta y como podria hacer para Visual Studio 2010Anonymous
August 25, 2012
The comment has been removedAnonymous
December 19, 2012
jummm, no me funcionó la documentación... hice tal cual lo del video, después me salieron muchos warnings, y al desactivar el checkbox de las propiedades del proyecto para el xml, no me salía ningun warning, sin embargo después de compilar varias veces me funcionó y estando checkeado la opcion del xml no me generó warning alguno. lo cual se me hace extraño. después fuí al SandCastle y agregué el xml, y mientras compilaba generó un error y no funcionó. tengo Visual Studio 2012 ultimate (trial). Generating reflection information... [C:WindowsMicrosoft.NETFramework64v4.0.30319MSBuild.exe] MRefBuilder (v2.7.2.0) Copyright ¸ 2006-2012, Microsoft Corporation, All Rights Reserved Info: Loaded 1 assemblies for reflection and 1 dependency assemblies. MREFBUILDER : error : Unresolved assembly reference: Windows (Windows, Version=255.255.255.255, Culture=neutral, PublicKeyToken=null) required by HelloWorld [C:UsersMiguelDesktopHelpWorkingGenerateRefInfo.proj] Last step completed in 00:00:05.3837 </buildStep> <buildStep step="Failed">Anonymous
January 01, 2013
Hola Claudio. En los sitios mencionados, aparecen también las versiones para 2010Anonymous
January 01, 2013
Miguel, pudiste resolver el problema, he probado con varias configuraciones y no me falla.