Descargar Ejemplo MethodDoc.zip
Una de las posibilidades que brinda C# .NET 2003 para poder Documentar (describir y ayudar al programador que utilizará nuevos objetos) es generar Comentarios en los archivos de código y almacenar estos Comentarios en un archivo XML separado. En los archivos de código habrá que utilizar tres caracteres «/» (///) antes de tipos definidos por el usuario como clases, delegados o interfases. Asimismo, también es posible agregar Comentarios a miembros como campos, eventos, propiedades y métodos. Al momento de Generar la aplicación (Build) se creará en forma automática el archivo de Comentarios.
Veamos un Paso a Paso:
1) En las Propiedades del Proyecto actual (en C#), seleccionar Propiedades de Configuración, seleccionar Build, y agregar, en la sección de Outputs, en el campo XML Documentation File, el nombre de un archivo XML donde se almacenarán los comentarios. Verificar que la opción (en esa misma sección) Generate Debugging Information, esté seteada a «True». Asimismo, veamos que el lugar por defecto donde se guardará este archivo es «binDebug».
NOTA: La implementación de este mecanismo fuerza al Compilador a mostrar mensajes de Advertencia «Compiler Warning (level 4) CS1591» para cada miembro o tipo público visible (público) que no haya sido descripto mediante los tags
NOTA 2: Esta funcionalidad se agregó a Visual Studio 2005, a través del Diseñador de Clases.
2) Generemos en el Proyecto actual un nuevo archivo tipo Clase. Veamos un ejemplo:
namespace MethodDoc
{
/// <summary>
/// Descripción genérica de la Clase
/// </summary>
class MyClass
{
public int x, y;
// Default constructor:
public MyClass()
{
x = 0;
y = 0;
}
/// <summary>
/// Descripcion del Método MyClass(int x, int y)
/// </summary>
/// <param name=»x»>Describe el tipo y la funcionalidad del Primer parámetro</param>
/// <param name=»y»>Describe el tipo y la funcionalidad del Segundo parámetro</param>
public MyClass(int x, int y)
{
this.x = x;
this.y = y;
}
// Override the ToString method:
public override string ToString()
{
return(String.Format(«({0},{1})», x, y));
}
}
}
Como se puede ver aparecen líneas con 3 slashes (///) que se ocuparán se describir los comentarios. Estas líneas comienzan con el Tag
. Entre ambas se agrega la descripción del Comentario. Asimismo, en el caso de querer comentar los parámetros de un Método, por debajo del Tag de cierre de summary, se agrega el Tag , a continuación su descripción, y se cierra con el Tag . Toda esta información se almacenará en el archivo XML de Comentarios definido anteriormente en la Configuración del Proyecto. Veamos cómo se auto-generó el archivo:
<doc>
<assembly>
<name>MethodDoc</name>
</assembly>
<members>
<member name=»T:MethodDoc.Form1″>
<summary>
Summary description for Form1.
</summary>
</member>
<member name=»F:MethodDoc.Form1.components»>
<summary>
Required designer variable.
</summary>
</member>
<member name=»M:MethodDoc.Form1.#ctor»>
<summary>
Summary description for Form1.
</summary>
</member>
<member name=»M:MethodDoc.Form1.Dispose(System.Boolean)»>
<summary>
Clean up any resources being used.
</summary>
</member>
<member name=»M:MethodDoc.Form1.InitializeComponent»>
<summary>
Required method for Designer support – do not modify
the contents of this method with the code editor.
</summary>
</member>
<member name=»M:MethodDoc.Form1.Main»>
<summary>
The main entry point for the application.
</summary>
</member>
<member name=»T:MethodDoc.MyClass»>
<summary>
Descripción genérica de la Clase
</summary>
</member>
<member name=»M:MethodDoc.MyClass.#ctor(System.Int32,System.Int32)»>
<summary>
Descripcion del Método MyClass(int x, int y)
</summary>
<param name=»x»>Describe el tipo y la funcionalidad del Primer Parámetro</param>
<param name=»y»>Describe el tipo y la funcionalidad del Segundo Parámetro</param>
</member>
</members>
</doc>
Podemos notar en este archivo cómo el Compilador agrega información de tipo ID string para cada construcción definida en el código donde se utilizaron Tags para generar documentación, por ejemplo,
{
MyClass point1 = new MyClass();
Point point2 = new Point();
}
Se definieron 2 objetos (MyClass y Point) para tener idea como Intellisense brinda información de objetos de espacios de nombre integrados (struct System.Drawing.Point) y sobre objetos pertenecientes a espacios de nombres definidos por el usuario (class MethodDoc.MyClass) para este ejemplo.
Resta recordar que para obtener información a través de Intellisense basta con poner el puntero del mouse sobre el nombre del objeto del cual se quiere obtener información, y para obtener la descripción de los tipos de parámetros que alimentan las distintas sobrecargas (overloads), basta con tipear el nombre del objeto, abrir un paréntesis «(» y allí el Intellisense mostrará como ToolTip las distintas formas de completar los métodos sobrecargados como así también la descripción del Comentario que se haya descripto en la clase que lo contiene.
