Documentar con XML, Visual Studio 2008, SandCastle y HTML Help Workshop

La documentación de nuestro código es una tarea no muy entretenida, pero necesaria. Las herramientas SandCastle y HTML Help WorkShop nos permite generar archivos partiendo de nuestra documentación XML. Lo primero, descargar e instalar las herramientas desde:

1. SandCastle  Version 2.4.10520
2. HTML Help WorkShop

Crear una solución con Visual Studio 2008 de tipo Librería de clases con el nombre “Ventas.DataAccess”, que tenga una clase Producto, la cual tendrá un método y dos propiedades.

   1:  

   2: Public Class Producto

   3:  

   4:     Private _CodProducto As String

   5:     Public Property CodProducto() As String

   6:         Get

   7:             Return _CodProducto

   8:         End Get

   9:         Set(ByVal value As String)

  10:             _CodProducto = value

  11:         End Set

  12:     End Property

  13:  

  14:     Private _Precio As Decimal

  15:     Public Property Precio() As Decimal

  16:         Get

  17:             Return _Precio

  18:         End Get

  19:         Set(ByVal value As Decimal)

  20:             _Precio = value

  21:         End Set

  22:     End Property

  23:  

  24:     Public Function GetProductos(ByVal strCodCat As String) As DataTable

  25:         Dim dt As New DataTable

  26:  

  27:         Return dt

  28:     End Function

  29:  

  30: End Class

Empecemos con la documentación. Al inicio de la clase escribimos tres veces el apostrofe (‘) y de forma automática se crea las siguientes etiquetas:

   1: ''' <summary>

   2: ''' 

   3: ''' </summary>

   4: ''' <remarks></remarks>

   5: Public Class Producto

   6:  

   7:  

   8: End Class

Para el caso del método se muestra así:

   1: ''' <summary>

   2:    ''' Obtiene la relacion de productos de una determinada categoria

   3:    ''' </summary>

   4:    ''' <param name="strCodCat">Codigo de Categoria</param>

   5:    ''' <returns>Objeto DataTable</returns>

   6:    ''' <remarks></remarks>

   7:    Public Function GetProductos(ByVal strCodCat As String) As DataTable

   8:        Dim dt As New DataTable

   9:  

  10:        Return dt

  11:    End Function

Se tiene mas etiquetas que se agregan manualmente. Revise http://msdn.microsoft.com/es-es/library/ms172653(v=VS.80).aspx

Finalmente mi clase Producto, tiene toda esta documentación:

   1: ''' <summary>

   2: ''' Clase Productos

   3: ''' </summary>

   4: ''' <remarks>Entidad de negocio Producto</remarks>

   5: Public Class Producto

   6:  

   7:  

   8:     ''' <summary>

   9:     ''' Codigo de Producto

  10:     ''' </summary>

  11:     ''' <remarks></remarks>

  12:     Private _CodProducto As String

  13:     Public Property CodProducto() As String

  14:         Get

  15:             Return _CodProducto

  16:         End Get

  17:         Set(ByVal value As String)

  18:             _CodProducto = value

  19:         End Set

  20:     End Property

  21:  

  22:  

  23:     ''' <summary>

  24:     ''' Precio de venta del producto

  25:     ''' </summary>

  26:     ''' <remarks></remarks>

  27:     Private _Precio As Decimal

  28:     Public Property Precio() As Decimal

  29:         Get

  30:             Return _Precio

  31:         End Get

  32:         Set(ByVal value As Decimal)

  33:             _Precio = value

  34:         End Set

  35:  

  36:         ''' <summary>

  37:         ''' Obtiene la relacion de productos de una determinada categoria

  38:         ''' </summary>

  39:         ''' <param name="strCodCat">Codigo de Categoria</param>

  40:         ''' <returns>Objeto DataTable</returns>

  41:         ''' <remarks></remarks>

  42:     Public Function GetProductos(ByVal strCodCat As String) As DataTable

  43:         Dim dt As New DataTable

  44:  

  45:         Return dt

  46:     End Function

  47:  

  48: End Class

Una vez completado toda la documentación de clases, métodos, propiedades, etc. Pasemos a generar el ensamblado en la carpeta Debug tendrás:

El archivo Ventas.Data.Access.xml tiene la documentación. En la carpeta C:\Program Files (x86)\Sandcastle\Examples\Generic ejecuta el programa SandcastleGui.exe

Agregue el ensamblado, el archivo XML y finalmente escriba un nombre al proyecto

SandCastle tiene tres estilos para generar la documentación: VS2005, hana y prototype, para la demo es suficiente con vs2005, pero las otras no están nada mal.

Para generar los archivos haga clic en el botón BUILD, es necesario ingresar un nombre de proyecto.  En la carpeta C:\Program Files (x86)\Sandcastle\Examples\DemoDocumentacion\vs2005\chm se ha creado tres archivos con extension .hhc, hhk y hhp.

 

Haga doble clic en DemoDocumentacion.hhp, debe cargarse el HTML Help WorkShop, active la opción de compilación y listo ya tenemos nuestro archivo DemoDocumentacion.chm

Así quedaría el archivo CHM

Aquí tienes un excelente artículo en el MSDN Magazine: Documentar el código con comentarios XML

Saludos :)