Buenas,
Estas navidades he sufrido el tan temido periodo de documentación técnica de proyectos, lo que me ha costado mas de una contractura muscular :s
Con tanto tiempo teniendo que buscar información y escribiendo words y mas words, he encontrado la herramienta perfecta para olvidarte de la documentación de tus proyectos en Visual Studio 2003 y 2005.
Sin embargo, solo pondré aquí el howto para VS2005, dejando para vosotros los links de ayuda para 2003.
1) Descargar:
The Visual Studio 2005 SDK
http://msdn.microsoft.com/vstudio/extend/default.aspx
HTML 2.x files Freeware viewer * (opcional)
http://www.helpware.net/mshelp2/h2viewer.htm
SandCastle June 2008 (2.4)
http://www.codeplex.com/Sandcastle/Release/ProjectReleases.aspx?ReleaseId=9921
- Devereis instalarlo en el directorio:
X:\Archivos de programa\Visual Studio 2005 SDK\2007.02\VisualStudioIntegration\Tools\Sandcastle (una vez hayais instalado el VS SDK 2005, claro).
Sandcastle Help File Builder
http://www.codeplex.com/SHFB/Release/ProjectReleases.aspx?ReleaseId=9848 (installer)
2) Instalar en el mismo orden de descarga
Ahora ya tenemos el equipo preparado para documentar automaticamente:
1) Como documentar el código:
Para poder documentar automaticamente, es necesario que usar los comentarios xml para el código. Para ello usaremos:
C#:
Tenemos esta función
public int Funcion(int a)
{
return a*a;
}
Colocamos el cursor al principio de la linea anterior a la declaración:
|
public int Funcion(int a)
{
return a*a;
}
Pulsamos 3 veces la barra "/" y automáticamente aparecerá:
/// <summary>
/// AQUI VA EL RESUMEN DE LA FUNCION
/// </summary>
/// <param name="a">DESCRIPCION DEL PARAMETRO</param>
/// <returns>LO QUE DEVUELVE.</returns>
public int Funcion(int a)
{
return a*a;
}
Estos comentarios son validos para:
Clases
Campos
Propiedades
Funciones
Enumeradores
Delegados
..
Es decir, prácticamente todo. Al poner las 3 barras, se generara automáticamente según lo que se este documentando, si la función es void no pondrá el return, etc, etc.
VB .NET:
Es EXACTAMENTE IGUAL, cambiando las 3 barras por 3 apostrofes " ' ".
''' <summary>
''' AQUI VA EL RESUMEN DE LA FUNCION
''' </summary>
''' <param name="a">DESCRIPCION DEL PARAMETRO</param>
''' <returns>LO QUE DEVUELVE.</returns>
public int Funcion(int a)
{
return a*a;
}
2) Como generar el archivo de comentarios:
Explorador de soluciones, click derecho sobre el proyecto deseado: Propiedades.
Pagina de propiedades / Generar: Marcamos ARCHIVO DE DOCUMENTACION XML.
Recomiendo dejar el path automático.
Compilar al gusto.
3) Como crear la documentación:
Inicio / Programas / SandCastle Help File Builder / SandCastle Help File Builder GUI.
Añadimos los archivos (.dll / .exe) deseados (acordaos de haberlos compilado con la casilla documentación marcada).
Y sin tocar nada ya podemos crear la documentación con el botón: BUILD (o menú Documentation / Build Project).
Y a esperar! Porque tarda lo suyo.
A partir de aquí como veréis podéis cambiar mil cosas, por ejemplo hacer un website en vez de un chm y mil cosas mas (lenguaje, títulos, dependencias...).
Espero que os sirve de ayuda, a mi me va a quitar un gran peso de encima!
Nota: puedo postear imagenes para amenizar el post? Comor?
Actualizaciones:
- 2008.01.27
.... - Borradas descargas innecesarias.
.... - Aclaraciones de instalación.
