Después de la muerte prematura de NDOC 2.0 Microsoft ha liberado una utilidad que 'lo sustituye', llamada Sandcastle.
Para aquellos que no lo sepan, estas utilidades permiten generar documentación de código a partir de los assemblies y sus correspondientes documentos XML que genera por ejemplo Visual Studio, a partir de los comentarios del código. Usa además Reflection para obtener documentación adicional de las posibles dependencias que pueda usar nuestra aplicación.
Tenía previsto describir a la vuelta de vacaciones como funciona Sandcastle ya que es una herramienta un poco dura de usar, únicamente mediante línea de comandos, pero he encontrado un Wiki sobre el tema que no conocía y que hace referencia a algunas utilidades que ya se han escrito por ahí que proporcionan un interface de usuario para Sandcastle, con lo que se hace un poco irrelevante escribir ya sobre cómo usar los comandos para generar la documentación.
Una de las que más me ha gustado es 'Sandcastle Help File Builder' que tiene un interface de usuario casi idéntico al que tiene NDOC con lo que usarla se hace muy sencillo para los que ya hemos usado esa herramienta (si no se ha usado, es muy fácil de aprender).
Para usarla, lo primero que se necesita tener instalado es Sandcastle, al menos con la CTP de Agosto de 2006. Una vez hecho esto, simplemente hay que seleccionar un assembly que hayamos compilado con la opción de generación de documentación XML en Visual Studio y pedirle a la utilidad que compile el archivo de ayuda. La salida de SandCastle se ve en la parte inferior de la ventana mostrando si se ha producido algún error. Si todo ha funcionado como debiera, la herramienta generará un archivo de ayuda con la documentación del código.
Una opción interesante que incluye esta utilidad es la de poder abrir directamente un proyecto o solución de Visual Studio para que la herramienta lo inspeccione y cargue los assemblies de salida, agilizando aún más el proceso.
Una pequeña pega ocurre si pasamos a la utilidad un assembly o proyecto de .NET Compact Framework. Si lo hacemos sin más, veremos un error similar al siguiente (para un proyecto con UI):
Error: Unresolved assembly reference: System.Windows.Forms (System.Windows.Forms, Version=2.0.0.0, Culture=neutral, PublicKeyToken=969db8053d3322ac) required by …
Para poder generar documentación de .NET Compact Framework adecuadamente, hay que indicarle a la utilidad que busque las dependencias de los assemblies de .NET Compact Framework en el sitio correcto ya que si no lo hacemos, intentará buscarlas en el GAC del PC en el que se ejecute, donde no las encontrará. Para ello simplemente hay que incluir en la colección de dependencias de la utilidad (en la sección Build) el directorio en el que se encuentran los assemblies correspondientes; que en una instalación en los directorios por defecto de Visual Studio y sustituyendo X.X por la versión correspondiente de .NET Compact Framework será similar a
C:Program FilesMicrosoft Visual Studio 8SmartDevicesSDKCompactFrameworkX.XvX.XWindowsCE
Una vez incluido el directorio en las dependencias, se puede compilar el archivo de ayuda sin problemas.
Pues a mí me sigue dando el error ese :-(.
Creo que debe tratarse de algún problema con la versión de la compact framework, dentro de la carpeta que señalas me aparece lo siguiente:
C:Program FilesMicrosoft Visual Studio 8SmartDevicesSDKCompactFramework2.0v1.0WindowsCE
Pero no existe el directorio 2.0v2.0…
¿Alguna idea de cómo puedo añadir las clases de la 2.0? ¿Dónde estará instalada? (porque mi proyecto la usa, eso seguro jeje).
Un saludo y gracias por el artículo ;-).
Usas Visual Studio 2005, ¿verdad? ¿Qué SDKs tienes instalados?
Tengo una consulta con respecto al Sancastle, ya logro generar la documentacion de una aplicacion de escritorio, pero el Sancastle pide el XML que es generado del la aplicacion de escritorio, ahora mi consulta es para aplicaciones Web, la aplicacion no me aparece dicho XML y en sus propiedades del proyecto Web no hay como sacarlo, saben como poder generar dicha XML para las aplicaciones Web, capaz alla que confiugrar algo o no se, estoy usando el Visual Studio 2005.
Saludos
Los XML se generan automaticamente en la carpeta BIN de tu proyecto.
Por defecto la opcion esta habilitada en las propiedades del proyecto, espero que no la hayas desactivado.
Saludos