DotNetcr.com
Si deseas hacer un intercambio de links con DotNetcr, escríbenos aquí
Recibe las actualizaciones vía RSS
Te invitamos a unirte en nuestras redes
   http://www.facebook.com/DotNetcr
   http://www.twitter.com/dotnetcr

Como agregar comentarios a tipos y miembros definidos por el usuario

Por aconsult | 10/16/2005 | Visitas 10,818 | Voto 0.00
Paso a Paso que describe como se puede documentar código en C# mediante un archivo XML. Util para aprovechar Intellisense en la descripción de métodos y propiedades de una nueva clase.
Categorías : C#, XML
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 "bin\Debug".



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, . Los ID strings se pueden identificar mediante un sólo caracter seguido del símbolo ":" (dos puntos). Por ejemplo:

N: NameSpace (Espacio de Nombres)
T: Type (Tipo: clase, interfase, estructura, enum, delegado)
F: Field (Campo)
P: Property (Propiedad)
M: Method (Método)
E: Event (Evento)

3) Para verificar que el Intellisense funciona de la manera esperada, areguemos al Proyecto actual un uevo archivo tipo Form y agreguemos las siguientes líneas de código:

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
Area de Comentarios
Por Anónimo - Fecha: 2006/08/20 11:57 AM
merci
Por Anónimo - Fecha: 2006/11/09 10:08 PM
eeewee
Por Anónimo - Fecha: 2007/01/14 03:12 PM
Exelente ..eso buscaba...
Por Anónimo - Fecha: 2007/06/12 01:26 PM
Que fragmento tan espectacular....
Felicidades al escritor por sentir con esa fuerza...

No solo de código viven los programadores...
Por Anónimo - Fecha: 2008/01/14 10:02 AM
Muy Bueno, adoro C#, pero ...

Sabe alguno de ustedes si esto funciona par Visual Basic 2003 ??
Por Anónimo - Fecha: 2008/10/01 04:00 PM
gracias
www.alexsam.tk
Por Anónimo - Fecha: 2011/10/11 11:24 AM
Evocero Anuncios

Ahora pueden publicar anuncios gratis tambien aqui es un nuevo sitio http://anuncios.evocero.com
Por Anónimo - Fecha: 2011/12/10 12:47 AM
Hello! dgeackb interesting dgeackb site! I'm really like it! Very, very dgeackb good!
Por Anónimo - Fecha: 2011/12/10 12:48 AM
Very nice site! [url=http://apeyixo.com/ysyxqys/2.html]cheap cialis[/url]
Por Anónimo - Fecha: 2011/12/10 12:48 AM
Very nice site! cheap cialis http://apeyixo.com/ysyxqys/4.html
Por Anónimo - Fecha: 2011/12/10 12:49 AM
Very nice site!
Por Anónimo - Fecha: 2011/12/10 12:49 AM
Hello! kgeddee interesting kgeddee site! I'm really like it! Very, very kgeddee good!
Por Anónimo - Fecha: 2011/12/10 12:49 AM
Very nice site! [url=http://apeyixo.com/ysyxqys/2.html]cheap cialis[/url]
Por Anónimo - Fecha: 2011/12/10 12:49 AM
Very nice site! cheap cialis http://apeyixo.com/ysyxqys/4.html
Por Anónimo - Fecha: 2011/12/10 12:50 AM
Very nice site!
Por Anónimo - Fecha: 2012/09/26 02:38 PM
Pretty nice post. I just stumbled upon your blog and wnated to say that I have truly enjoyed surfing around your blog posts. After all I’ll be subscribing to your feed and I hope you write again soon!
Por Anónimo - Fecha: 2012/09/28 01:57 AM
EE5sap , [url=http://vqisrzmjuqik.com/]vqisrzmjuqik[/url], [link=http://beimlqggcekb.com/]beimlqggcekb[/link], http://gehkrsjvnynv.com/
Por Anónimo - Fecha: 2012/09/29 02:03 PM
qHppjS , [url=http://rhyjqfksmhxj.com/]rhyjqfksmhxj[/url], [link=http://dizoemszpexe.com/]dizoemszpexe[/link], http://icoowfgbamum.com/
Por Anónimo - Fecha: 2015/12/17 03:34 PM
I wanetd to spend a minute to thank you for this.
Por Anónimo - Fecha: 2015/12/19 02:50 AM
| Good post Robert — great overview — jQuery can be trckiy at first (it was for me) but once you get it' …it can really improve the user's experience and the overall quality of your work. Oh, and nice blog! http://ljpasfotvbl.com [url=http://gqcakwou.com]gqcakwou[/url] [link=http://jpkbextm.com]jpkbextm[/link]
Por Anónimo - Fecha: 2015/12/20 02:22 PM
Summary: I would like to discuss a colupe of technical difficulties I've encountered with the site. Is there a way to separate a listing of posts by anything else other than a , ?May I have a list of the shortcodes available?Is it possible to have the CBM plugin to be able to try and convert it to fit in with Sauder's payment gateway?Desired time: 2:00-2:30 http://ojmywkjv.com [url=http://mhjltkgxt.com]mhjltkgxt[/url] [link=http://ieclzwane.com]ieclzwane[/link]
Ingrese su Comentario
Comentario
Para poder votar debe estar registrado en DotNetcr.com
Solo queda registrado el primer voto enviado
Voto


Últimos Recursos
ricardo leppe t
pedrojavier
CALIN
willipinru
richard
ragomez
PER 238
MEX 236
CRI 188
COL 118
ESP 105
ARG 88