Calificación:
  • 0 voto(s) - 0 Media
  • 1
  • 2
  • 3
  • 4
  • 5
[Tutorial] C# Documentación XML
#1


Tutorial de documentación XML
Visual Studio .NET 2003
Este tutorial muestra cómo documentar código mediante XML.

Archivos de ejemplo

Vea Ejemplo de documentación XML para descargar y generar los archivos de ejemplo que se utilizan en este tutorial.

Información adicional

/doc (Procesar comentarios de documentación)
Etiquetas recomendadas para comentarios de documentación
Delimitadores para etiquetas de documentación
Procesar el archivo XML
Glosario de XML
Tutorial

C# proporciona un mecanismo para que los programadores puedan documentar el código mediante XML. En los archivos de código fuente, las líneas que empiezan con /// y que preceden a un tipo definido por el usuario (tal como una clase, un delegado o una interfaz), a un miembro (como un campo, evento, propiedad o método) o a una declaración de espacio de nombres se pueden procesar como comentarios e incluir en un archivo.

Ejemplo

El siguiente ejemplo proporciona una descripción básica de un tipo documentado. Para compilar el ejemplo, escriba lo siguiente en la línea de comandos:

csc XMLsample.cs /doc:XMLsample.xml
Se creará el archivo XMLsample.xml, el cual se puede ver en el explorador o con el comando TYPE.

// XMLsample.cs
// compile with: /doc:XMLsample.xml
using System;

/// <summary>
/// Class level summary documentation goes here.</summary>
/// <remarks>
/// Longer comments can be associated with a type or member
/// through the remarks tag</remarks>
public class SomeClass
{
/// <summary>
/// Store for the name property</summary>
private string myName = null;

/// <summary>
/// The class constructor. </summary>
public SomeClass()
{
// TODO: Add Constructor Logic here
}

/// <summary>
/// Name property </summary>
/// <value>
/// A value tag is used to describe the property value</value>
public string Name
{
get
{
if ( myName == null )
{
throw new Exception("Name is null");
}

return myName;
}
}

/// <summary>
/// Description for SomeMethod.</summary>
/// <param name="s"> Parameter description for s goes here</param>
/// <seealso cref="String">
/// You can use the cref attribute on any tag to reference a type or member
/// and the compiler will check that the reference exists. </seealso>
public void SomeMethod(string s)
{
}

/// <summary>
/// Some other method. </summary>
/// <returns>
/// Return results are described through the returns tag.</returns>
/// <seealso cref="SomeMethod(string)">
/// Notice the use of the cref attribute to reference a specific method </seealso>
public int SomeOtherMethod()
{
return 0;
}

/// <summary>
/// The entry point for the application.
/// </summary>
/// <param name="args"> A list of command line arguments</param>
public static int Main(String[] args)
{
// TODO: Add code to start application here

return 0;
}
}
Descripción del código

La documentación XML empieza con ///. Cuando se crea un proyecto nuevo, el asistente agrega automáticamente algunas líneas iniciales con ///. El procesamiento de estos comentarios presenta algunas restricciones:

La documentación debe estar en XML bien formado. Si el XML no está bien formado, se generará un error de advertencia y el archivo de documentación incluirá un comentario que mencione el error encontrado. Para obtener más información sobre XML bien formado, vea Glosario de XML.
Los programadores pueden crear su propio conjunto de etiquetas. Existe un conjunto de etiquetas recomendado (vea la sección Información adicional). Algunas de las etiquetas recomendadas tienen significados especiales:
La etiqueta <param> se usa para describir parámetros. Cuando se utiliza, el compilador comprueba si el parámetro existe y si todos los parámetros están descritos en la documentación. Si la comprobación no tiene éxito, el compilador emite una advertencia.
El atributo cref se puede asociar a cualquier etiqueta para proporcionar una referencia a un elemento de código. El compilador comprobará si existe ese elemento de código. Si la comprobación no tiene éxito, el compilador emite una advertencia. El compilador también respeta cualquier instrucción using cuando busca un tipo descrito en el atributo cref.
La etiqueta <summary> la utiliza IntelliSense, dentro de Visual Studio, para mostrar información adicional acerca de un tipo o un miembro.
Resultados del ejemplo

Éste es el archivo XML que resulta de la clase anterior:

<?xml version="1.0"?>
<doc>
<assembly>
<name>xmlsample</name>
</assembly>
<members>
<member name="T:SomeClass">
<summary>
Class level summary documentation goes here.</summary>
<remarks>
Longer comments can be associated with a type or member
through the remarks tag</remarks>
</member>
<member name="F:SomeClass.myName">
<summary>
Store for the name property</summary>
</member>
<member name="M:SomeClass.#ctor">
<summary>The class constructor.</summary>
</member>
<member name="M:SomeClass.SomeMethod(System.String)">
<summary>
Description for SomeMethod.</summary>
<param name="s"> Parameter description for s goes here</param>
<seealso cref="T:System.String">
You can use the cref attribute on any tag to reference a type or member
and the compiler will check that the reference exists. </seealso>
</member>
<member name="M:SomeClass.SomeOtherMethod">
<summary>
Some other method. </summary>
<returns>
Return results are described through the returns tag.</returns>
<seealso cref="M:SomeClass.SomeMethod(System.String)">
Notice the use of the cref attribute to reference a specific method </seealso>
</member>
<member name="M:SomeClass.Main(System.String[])">
<summary>
The entry point for the application.
</summary>
<param name="args"> A list of command line arguments</param>
</member>
<member name="P:SomeClass.Name">
<summary>
Name property </summary>
<value>
A value tag is used to describe the property value</value>
</member>
</members>
</doc>
Nota El archivo XML no proporciona información completa acerca del tipo y los miembros (por ejemplo, no contiene ninguna información de tipos). Para obtener información completa acerca de un tipo o miembro, el archivo de documentación debe utilizarse conjuntamente con el mecanismo de reflexión sobre el tipo o el miembro real.




Posibles temas similares...
Tema Autor Respuestas Vistas Último mensaje
Información [Tutorial] Certificado SSL Gratis StartSSL 2016 Tutorial DarkMaster 26 5,108 28-04-2016, 03:39 AM
Último mensaje: Lob3zNo
Bombilla [Tutorial] SSL Gratis, Conseguir e Instalar Certificado DarkMaster 16 871 06-01-2016, 01:32 AM
Último mensaje: DarkMaster
  [PUBLICO] Tutorial Botones con perspectiva 3D AngelKrak 0 234 17-01-2015, 05:44 AM
Último mensaje: AngelKrak
  [Tutorial] Aumentar el Tamaño Máximo al Cargar Archivos con PHP y Apache papanoel 0 668 22-01-2014, 04:38 AM
Último mensaje: papanoel
  Tutorial Css Primera Parte para phpost JNeutron 4 1,052 24-02-2013, 04:01 AM
Último mensaje: Echizen
  [TUTORIAL] Conexión a una Base de Datos desde [PHP] lapipichapa 0 491 15-02-2013, 05:52 PM
Último mensaje: lapipichapa
  Tutorial de .htaccess | Control de acceso a carpetas diringax 11 1,453 13-01-2013, 12:28 PM
Último mensaje: papi
  [TUTORIAL] Como evitar el Hotlinkeo (robo de imágenes) Taquion 8 1,689 12-01-2013, 05:50 PM
Último mensaje: natestale
  Tutorial | Crear Sistema de Login PHP diringax 13 1,741 18-12-2012, 01:49 AM
Último mensaje: BrayanFG
  [Tutorial] Dominios virtuales para localhost Alan71 25 2,207 18-12-2012, 01:44 AM
Último mensaje: BrayanFG



Usuarios navegando en este tema: 1 invitado(s)