Muchas veces se nos olvida documentar determinadas partes del código, y con el tiempo ello conlleva a una, aunque mínima, importante pérdida de tiempo. Con Visual Studio .NET se nos pone más fácil el olvidarnos de dichos comentarios con la posibilidad de documentar mediante XML los proyectos .NET.  Pues bien veamos un ejemplo de documentación tipo MSDN, integración con IntelliSense y con el IDE de Visual Studio .NET.

Software utilizado

Visual Studio .NET 2003, NDoc 1.3, Microsoft Visual Studio .NET Help Integration Kit, Microsoft Html Workshop, H2Reg Helpware.

Contenido

-              Sobre los comentarios... un comentario.

-              Ejemplo con Visual C#

-              Integración con NDoc y creación de HTML Help 2

-              Integración con IDE de Visual Studio .NET

-              Para finalizar

Más que un simple comentario

Hasta ahora estábamos acostumbrados que en el mejor de los casos en los que nos habíamos decidido o acordado de insertar (nosotros o nuestros compañeros) comentarios, éste solía ser ‘semi-indio’, poco entendible y en ocasiones confuso.

La posibilidad que nos ofrece Visual Studio .NET de insertar comentarios como si fueran tags de XML, que de hecho lo son (lo veremos más adelante), siguiendo una sintaxis propia posibilita la documentación íntegra de proyectos, incluyendo sus clases, métodos, atributos, enumeradores, etcétera. Así, es posible que para una clase demos una explicación de cual es su utilidad, remarcando información importante de utilización, que para sus métodos aportemos, no sólo la explicación de su funcionalidad, sino también la explicación de los parámetros con sus tipos, y en el caso que sea una función que tipo devuelve y como se interpreta. Además podremos indicar referencias a otros temas relacionados e incluso poner código de ejemplo.

Todo esto es un paso hacia delante si hacemos un buen uso de ello, así que en este artículo veremos como documentar un proyecto de ejemplo, como crear una ayuda o documentación muy parecida (por no decir idéntica) a la que nos brinda MSDN y como integrarlo en nuestra IDE.      

Ejemplo con Visual C#..

En primer lugar documentaremos el código. Con Visual C# utilizaremos las tres barras (///) (que resultaran en tags basados en XML) en los métodos públicos para identificarlos, sea a nivel de clase, método, propiedad o valor de un enumerador. Es importante que sobretodo las públicas tengan una descripción ya que cuando se utilicen, el IDE de Visual describirá lo que hemos puesto. Fíjense en el ejemplo siguiente, nos hemos centrado en el comentario a nivel de clase y de un método estático (ShowInputBox) que es equivalente a una clase que implementa una especie de clase similar a la de InputBox de Visual Basic pero para Visual C#, con lo cual este ensamblado una vez acabado lo utilizaremos desde otras aplicaciones y necesitamos tener los comentarios.

 

Código Fuente  

using System;
using System.Windows.Forms;
 
namespace InputBox
{
   /// <summary>
   /// Clase equivalente InputBox de Visual Basic.
   /// </summary>
   /// <remarks>Devuelve DialogResult.OK en Aceptar o Intro.
   /// Devuelve DialogResult.Cancel en Cancelar o Escape.</remarks>
   /// <example>ESTO ES UN EJEMPLO
   /// <code>
   /// // utilización del Namespace InputBox
   /// using InputBox;
   /// // Llamada a InputBox.ShowInputBox con sobrecarga de 6 parámetros.
   /// InputBox.ShowInputBox("Entrar valor:" ,"Titulo InputBox","Valor por defecto", 50, 50,"http://www.elguille.info");
   /// </code>
   /// <c>Nótese que la llamada se realiza a un método estático.</c>
   /// </example>
  public class InputBox : System.Windows.Forms.Form
  {
            #region "Atributos"
            private System.Windows.Forms.Label lblInfo;
            private System.Windows.Forms.TextBox txtTexto;
            private System.Windows.Forms.Button button1;
            private System.Windows.Forms.Button button2;
            private System.Windows.Forms.LinkLabel lblLink;
            private System.ComponentModel.Container components = null;
            #endregion
 
            #region "Constructor/InitializeComponent/Dispose"
            private InputBox()
            {
                     InitializeComponent();
            }
 
            private void InitializeComponent()
            {
                     // 
                     // Generación automática
                     // 
            }
 
            #endregion
 
            #region "Métodos privados"
            private void InputBox_Load(object sender, System.EventArgs e)
            {
                     // 
                     // Lo que corresponda
                     //
            }
            private void textBox1_KeyDown(object sender,
                     System.Windows.Forms.KeyEventArgs e)
            {
                     // 
                     // Lo que corresponda
                     //
            }
            private void lblLink_LinkClicked(object sender, LinkLabelLinkClickedEventArgs e)
            {
                     ///
                     /// TODO: CODIGO PARA EL LINK
                     /// 
            }
            #endregion
 
               /// <summary>
               /// Ejecuta InputBox.
               /// </summary>
               /// <param name="prompt">Cadena de pregunta del InputBox.</param>
               /// <param name="title">Titulo del InputBox.</param>
               /// <param name="defaultValue">Valor por defecto en la casilla de entra de texto.</param>
               /// <param name="XPos">Posiciona el InputBox en la coordenada X horizontal.</param>
               /// <param name="YPos">Posiciona el InputBox en la coordenada Y vertical.</param>
               /// <param name="link">Muestra una etiqueta en forma de link para Ayuda o enlace a fichero o URL externo. Ver lblLink_LinkClicked</param>
               /// <returns>Devuelve cadena introducida por el usuario si DialgoResult es OK.</returns>
            public  static string ShowInputBox(string prompt,
                     string title, string defaultValue, 
                     int XPos, int YPos, string link)
            {
                     InputBox box = new InputBox();
                     
                     box.Text = title;
                     box.lblInfo.Text = prompt;
                     box.txtTexto.Text = defaultValue;
                     box.Location = new System.Drawing.Point(XPos,YPos);
                     box.lblLink.Text = link;
 
                     box.ShowDialog();
                     if (box.DialogResult.CompareTo(DialogResult.OK) == 0)
                              return box.txtTexto.Text;
                     else
                              return "";
            }
 
  }
 
}

Integración con NDoc y creación de HTML Help 2

 Al compilar el ensamblado debemos crear un archivo de documentación XML, opción /doc en el compilador y que podemos acceder desde las propiedades del proyecto en el apartado Generar de Propiedades de configuración (Ver Fig. 1) desde el IDE de Visual Studio .NET.

Fig1. Generar información de depuración generará el archivo de ayuda en formato XML.

Una vez compilado utilizaremos la aplicación NDoc. Ésta puede ser descargada desde  http://ndoc.sourceforge.net/ y crea una documentación a partir del archivo de documentación del proyecto Visual C# en distintos formatos como veremos a continuación.  Es un AddOn para Visual Studio .NET y está, como pueden ver, bajo SourceForge.

Crearemos un nuevo proyecto NDoc a partir de una solución .NET, en nuestro caso InputBox.sln. Ver Fig 2.

 

Fig2.- Creamos un nuevo proyecto NDoc a partir de la solución del proyecto de .NET.

 

Si desplegan el Combo Documentation Type verán una serie de formatos que NDoc trae de forma predeterminada; para la integración con Visual Studio .NET utilizaremos un formato que no viene con NDoc por defecto y que instalaremos a continuación. Cerramos el proyecto y el propio NDoc.

Para que se integre con el IDE de Visual Studio .NET debemos utilizar the Visual Studio .NET Help format (HTML Help 2),  que viene en Microsoft Visual Studio .NET Help Integration Kit (VSHIK2003).

Para que este tipo de fomato de ayuda se pueda compilar utilizaremos Microsoft Html Workshop.

Una vez ejecutados éstos abrimos de nuevo el NDoc y el proyecto referente anteriormente. Vemos en el desplegable el tipo VS.NET 2003 (Beta), que seleccionaremos. Asignamos las siguientes propiedades:

 

Propiedad	Valor
Document Main Settings
ClearIntermediates	True
CopyrightHref	http://www.webcorrespondiente.com
CopyrightText	© InputBox C# Class
FeedBackEmailAddress	jtorres_diaz@terra.es
GetExternalSummaries	False
HemlHelpName	InputBoxClass
IncludeAssemblyVersion	True
OutputDirectory	.\doc\
Title	InputBox C# Class
Html Help 2 Deployment
CollectionNamespace	InputBox
GenerateCollectionFiles	True
RegisterTitleAsCollection	True
RegisterTitleWithNamespace	True

 

Éstas son las más importantes para la creación de la ayuda en formato Html Help 2. Naturalmente el valor de las propiedades es arbitrario aunque si que aconsejo que las referentes a Html Help 2 Deployment sean todas a True, a excepción de CollectionNamespace, naturalmente.

 

Fig 3. Antes de compilar abremos seleccionados VS .NET  2003 (beta) y asignado las propiedades correspondientes.

 

A continuación generaremos (Build) el proyecto de NDoc el cual generará los ficheros resultantes por defecto en .\doc\.

 

Fig 4. Compilando los archivos de ayuda en formato Html Help 2

 

Si todo ha ido bien, en la carpeta docs del proyecto debe haber los siguientes archivos. (Ver fig. 5)

Fig 5. El resultado debe ser similar, con el nombre del proyecto correspondiente, si no es así quizás algún paso se le haya pasado por alto.

Registrar e Integrar con el IDE de Visual Studio .NET

Primero deberemos registrar la ayuda que acabamos de generar. Para ello utilizaremos la herramienta H2Reg. Se trata de una pequeña aplicación de consola de apenas 200 kb que permite registrar ayudas MS Help 2.x en la colección correspondiente.

Para utilizar H2Reg se ejecutará con en comando –r seguido de un fichero.ini que contendrá la información para registrar la ayuda en nuestro sistema. Este archivo .ini forma parte de unos de los archivos que ha generado NDoc, y se llama InputBoxClassCollection.h3reg.ini; así ejecutaremos:

C:\Program Files\Helpware\H2Reg\H2Reg.exe -r cmdfile=C:\InputBox\docs\InputBoxClassCollection.H2reg.ini

Si todo ha ido correctamente saldrá un pequeño formulario de registro que rápidamente desaparecerá; sino ha ido bien surgirá un formulario como en la figura 6.

 

Fig 6. Si nos muestran este formulario el proceso de registro no se ha llevado a cabo

 

Debemos asegurarnos de que existan todos los archivos anteriormente descritos y que la ubicación sea la correcta.

Cuando se registre podemos verlo en el Administrador de la colección de ayuda combinada de Visual Studio .NET(Ver Fig. 7)

Link: ms-help://MS.VSCC.2003/VSCCCommon/cm/CollectionManager.htm

Fig 7. Administrador de la colección de ayuda combinada de Visual Studio .NET

 

 Fíjense en InputBox C# Class, como registrado y activado.

Ahora abriremos un nuevo proyecto y referenciaremos el ensamblado correspondiente a InputBox. Si intentamos hacer uso de InputBox y ejecutamos su método virtual, fijémonos que pasa ( fig  8)

 

Fig 8. Una vez registrado la ayuda vemos la integración total con el IDE de Visual Studio.

 

Por un lado la clase InputBox esta ligada con la ayuda dinámica (parte inf. Derecha). La información rápida aparece con la descripción del método, la descripción de  los parámetros y tipos de datos de retorno del método. Además podremos utilizar InputBox en el filtrado de búsqueda (parte sup. Derecha) y ver la descripción que describimos de la clase con el ejemplo y demás (ver Fig. 9).

 

Fig 9. Ayuda referente a la Clase InputBox con el ejemplo que indicamos en el código.

Para finalizar

Ahora ya sabemos como documentar un librería extensa y como proveer a otros desarrolladores de nuestros comentarios y ejemplos y como éstos se muestran junto con la ayuda de otras librerías desde el mismo IDE de Visual Studio .NET.            

Hemos visto unas cuantas propiedades de NDoc a partir de ahora podrá investigar en la posibilidad de cada una de ellas.