El Bruno

Buenas

mi amigo Emilio, me impuso como tarea comentar algo sobre un addin IMPRESCINDIBLE para Visual Studio: GhostDoc. Hace tiempo, ya hablé sobre este AddIn, y también lo hice el 16 de Noviembre del 2005 cuando posteaba en MsnSpaces. Como trato de reaprovechar el trabajo, les dejo parte de un mail interno de Avanade que escribí hace un tiempo:

... cómo funciona, pues muy simple. Supongamos que poseemos la siguiente clase Customer:

 1 namespace GhostDocSample
 2 {
 3   public class Customer
 4   {
 5     public Customer(string CustomerName, string CustomerEMail)
 6     {
 7       _Name = CustomerName;
 8       _EMail = CustomerEMail;
 9     }
10     string _Name = "";
11     string _EMail = "";
12     public string GetCustomerCompleteInformation()
13     {
14       return string.Format("{0}; mailto:{1}", _Name, _EMail);
15     }
16     public void SetCustomerInformation(string CustomerName, string CustomerEMail)
17     {
18       _Name = CustomerName;
19       _EMail = CustomerEMail;
20     }
21   }
22 }

 

La clase Customer posee un código fuente muy simple, pero lamentablemente no posee una sola línea de documentación. Usualmente agregaríamos los prefijos “///” para que se genere la sección de documentación automáticamente y luego completaríamos la metadata de la misma. Pero con GhostDoc el trabajo es mucho más simple. Seleccionamos la función que queremos documentar y desplegamos el menú desplegable del IDE.

 

A continuación GhostDoc genera automáticamente la documentación para el constructor de la clase Customer. Utilizando el lenguaje natural en el que hemos descrito los elementos del constructor; GhostDoc ha podido generar lo siguiente.

 1 /// <summary>
 2 /// Initializes a new instance of the <see cref="Customer"/> class.
 3 /// </summary>
 4 /// <param name="CustomerName">Name of the customer.</param>
 5 /// <param name="CustomerEMail">The customer E mail.</param>
 6 public Customer(string CustomerName, string CustomerEMail)
 7 {
 8   _Name = CustomerName;
 9   _EMail = CustomerEMail;
10 }

 

La documentación general del constructor hace referencia a la clase Customer;  y en cada uno de los parámetros del constructor GhostDoc ha interpretado el significado de los mismos y ha creado la documentación correspondiente. Como podemos ver es muy poderoso, y si seguimos una buena práctica en lo referido a la nomenclatura que utilizamos para crear funciones y parámetros; el trabajo de documentar se hace mucho más fácil. Si terminamos de generar la documentación para toda la clase utilizando GhostDoc, el código de la misma queda como en el siguiente ejemplo:

 1 namespace GhostDocSample
 2 {
 3   public class Customer
 4   {
 5   /// <summary>
 6   /// Initializes a new instance of the <see cref="Customer"/> class.
 7   /// </summary>
 8   /// <param name="CustomerName">Name of the customer.</param>
 9   /// <param name="CustomerEMail">The customer E mail.</param>
10   public Customer(string CustomerName, string CustomerEMail)
11     {
12       _Name = CustomerName;
13       _EMail = CustomerEMail;
14     }
15   string _Name = "";
16   string _EMail = "";
17   /// <summary>
18   /// Gets the customer complete information.
19   /// </summary>
20   /// <returns></returns>
21   public string GetCustomerCompleteInformation()
22     {
23     return string.Format("{0}; mailto:{1}", _Name, _EMail);
24     }
25   /// <summary>
26   /// Sets the customer information.
27   /// </summary>
28   /// <param name="CustomerName">Name of the customer.</param>
29   /// <param name="CustomerEMail">The customer E mail.</param>
30   public void SetCustomerInformation(string CustomerName, string CustomerEMail)
31   {
32       _Name = CustomerName;
33       _EMail = CustomerEMail;
34   }
35 }

Otros de los aspectos interesantes de la versión actual de GhostDoc es que ahora también soporta VB.Net (en fase Beta).

Realmente aconsejable :D

Saludos

El Bruno