viernes, diciembre 3, 2021

Como agregar comentarios a tipos y miembros definidos por el usuario

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

, pero aún así la aplicación podrá ejecutarse.

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:

using System;

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


y terminan 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:

<?xml version=»1.0″?>
<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, private void Form1_Load(object sender, System.EventArgs e)
{
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.

Descargar Ejemplo MethodDoc.zip




Redes Sociales

2,736FansMe gusta
326SeguidoresSeguir

Popular esta semana

Calcular la distancia entre dos puntos geográficos en SQL Server

En este ejemplo mostramos como calcular la distancia en metros o kilómetros entre dos puntos geográficos, por latitud y longitud. El resultado lo obtenemos en metros o kilómetros.
SQL Server - Merge

MERGE en SQL Server para Insert, Delete y Update con dos tablas

Ejemplo práctico usando MERGE para sincronizar dos tablas, Insert, Update y Delete en un solo query. Válido para SQL SERVER 2008 o superior.

DELETE con subconsulta o INNER JOIN

En el siguiente ejemplo se explica la forma en que se pueden eliminar registros en nuestras tablas con instrucciones DELETE más complejas que las...

Últimos artículos

Flutter - Instagram Clone App

Instagram Clone App con Flutter

Marvin Stanley Valenzuela nos comparte un reto y genialidad a la vez, excelente práctica de la que podemos aprender mucho, diseñó en...

¿Cómo agregar una IP adicional en una VM Ubuntu en Azure?

Lo más común al momento de crear y configurar un nuevo servidor es que a este le asigne un solo IP, pero...
flutter one year

Después de un año con Flutter, esto es lo que aprendí

La historia comenzó cuando un día desperté pensando en tener un nuevo proyecto personal. Me dije a mí misma que hay muchas...
promocionar app

Cómo promocionar gratis tu app usando tappx

Como todos los que me siguen y mis redes sociales sabrán, recientemente lancé mi primera aplicación, pero más allá del desafío tecnológico de...