Barriers to information use

Una característica interesante del compilador de C# es que puede leer comen- tarios en un formato especial y generar documentación XML a partir de los co- mentarios. Puede entonces colocar este XML en la Web para facilitar un nivel extra de documentación a los programadores que necesiten comprender la estruc- tura de sus aplicaciones.

Para usar esta función, debe hacer dos cosas:

• Usar tres barras inclinadas para los comentarios. El compilador de C# no genera ninguna documentación XML para ningún documento que no em- piece con tres barras. Tampoco genera documentación XML para comen- tarios regulares de varias líneas.

• Use la opción /doc del compilador de C# para especificar el nombre del archivo que debería contener la documentación XML generada.

El listado 2.4 muestra la aplicación Hello World! con comentarios de docu- mentación XML.

Listado 2.4. La aplicación Hello World! con comentarios XML

/// La clase HelloWorld es la única clase de la

/// clase "HelloWorld". La clase implementa la función /// Main() de la aplicación. La clase no contiene otras /// funciones.

class HelloWorld {

/// Ésta es la función Main() para la clase del listado 2.4. /// No devuelve un valor y no toma ningún

/// argumento. Escribe el texto "Hello World!" en la /// consola y luego sale.

static void Main() {

System.Console.WriteLine("Hello World!"); }

}

Puede compilar esta aplicación con la opción /doc para generar documenta- ción XML para el código fuente:

csc /doc:HelloWorld.xml HelloWorld.cs

El compilador produce un HelloWorld.exe como era de esperar y tam- bién un archivo llamado HelloWorld.xml. Este archivo contiene un documento XML con sus comentarios de documentación XML incrustados en él. El listado 2.5 muestra el documento XML que se genera cuando se compila con la opción / doc el código del listado 2.4.

Listado 2.5. D o c u m e n t o X M L generado para el código del listado 2.4

<?xml version="1.0"?> < doc> <assembly> <name>HelloWorld</name> </assembly> <members> <member name="T:HelloWorld">

La clase HelloWorld es la única clase de la

clase "HelloWorld". La clase implementa la función Main() de la aplicación. La clase no contiene otras

funciones. </member>

<member name="M:HelloWorld.Main">

Esta es la función Main() para la clase del listado 2.4. No devuelve un valor y no toma ningún

argumento. Escribe el texto "HelloWorld!" en la consola y luego sale.

</member> </members> </doc>

Ahora puede escribir una hoja de estilo para este documento en XML y mos- trarlo en una página Web, proporcionando a los demás usuarios documentación actualizada de su código.

La principal porción del documento XML está en el elemento <members>. Este elemento contiene una etiqueta <member> para cada objeto documentado en el código fuente. La etiqueta <member> contiene un atributo, name, que designa al miembro documentado. El valor del atributo name empieza con un prefijo de una letra que describe el tipo de información en cuestión. La tabla 2.1 describe los posibles valores del atributo del nombre y su significado.

Tabla 2.1. Prefijos de atributo <member> "name=" Prefijo E F M N P T ! Significado

El elemento proporciona documentación de un evento. El elemento proporciona documentación de un campo. El elemento proporciona documentación de un método. El elemento proporciona documentación de un espacio de nombres.

El elemento proporciona documentación de una propiedad. El elemento proporciona documentación de un tipo defini- do por el usuario. Éste puede ser una clase, una interfaz, una estructura, una enumeración o un delegado.

El compilador C# encontró un error y no pudo determinar el prefijo correcto de este miembro.

Tras el prefijo se colocan dos puntos y el nombre del miembro. El atributo

name= indica el nombre de la clase para los miembros de tipo. Para los miem- bros de método, el atributo name= indica el nombre de la clase que contiene el método, seguida por un punto y a continuación el nombre del método.

Sus comentarios de documentación XML pueden incluir cualquier elemento XML válido para ayudarle en su tarea de documentación. La documentación de .NET Framework recomienda un conjunto de elementos XML que puede usar en su documentación.

El resto de esta sección examina cada uno de estos elementos. Recuerde que debe emplear XML válido en sus comentarios, lo que significa que cada elemento debe contener su elemento final correspondiente en alguna parte de sus comenta- rios.

NOTA: El término etiqueta se refiere a cualquier elemento descriptivo con-

tenido en el XML. Las etiquetas siempre están entre los símbolos < y >.

<c>

Puede usar la etiqueta <c> para indicar que una pequeña parte del comentario debe ser tratada como código. Las hojas de estilo pueden usar este elemento para mostrar la porción de código del comentario con una fuente de tamaño fijo, como Courier:

/// Ésta es la función <c>Main()</c> para la /// clase HelloWorld.

<code>

Puede usar la etiqueta < c o d e > para indicar que varias líneas de texto de sus comentarios deben ser tratadas como código:

/// Llamar a esta aplicación con tres argumentos

/// hará que la matriz de cadenas suministrada a Main() /// contenga tres elementos:

/// <code>

/// Argument[0]: command line argument 1 /// Argument[1]: command line argument 2 /// Argument[2]: command line argument 3 /// </code>

<example>

Puede usar la etiqueta < e x a m p l e > para indicar un ejemplo de cómo usar las clases que desarrolle a otros programadores. Los ejemplos suelen incluir una muestra de código y quizás quiera usar las etiquetas < e x a m p l e > y < c o d e > juntas:

/// <example>Aquí tiene un ejemplo de un cliente llamando /// a este código:

/// <code>

/// ponga aquí su código de ejemplo /// </code>

/// </example>

<exception>

Puede usar la etiqueta < e x c e p t i o n > para documentar cualquier excepción que pueda surgir en el código del miembro. La etiqueta < e x c e p t i o n > debe contener un atributo llamado cref cuyo valor especifica el tipo de excepción que se documenta. El valor del atributo cref debe estar entre comillas. El texto del elemento describe las condiciones en las que aparece la excepción:

/// <exception cref="System.Exception">

/// Aparece si el valor introducido es menor de 0. /// </exception>

El compilador de C# asegura que el valor del atributo cref sea un tipo de datos válido. Si no lo es, el compilador genera un mensaje de aviso. A continua- ción se indica cómo documentar una función M a i n ( ) :

/// <exception cref="junk">probando</exception>

hace que el compilador de C# genere un mensaje de aviso como el siguiente: aviso CS1574: El comentario en XML 'Main()' tiene un atributo cref

'junk' que no se encuentra

En este caso, el compilador de C# todavía escribe la etiqueta <exception> en el archivo XML, pero pone un signo de exclamación antes del atributo cref:

<member name="M:MyClass.Main">

<exception cref="!:junk">probando</exception> </member>

<list>

Puede usar la etiqueta < l i s t > para describir una lista de elementos en la documentación. Puede describir una lista no numerada, una lista numerada o una tabla. La etiqueta < l i s t > usa un atributo llamado type para describir el tipo de la lista. La tabla 2.2 enumera los posibles valores para el atributo type y describe su significado.

Tabla 2.2. Valores para el atributo "type" de la etiqueta <list>

Valor

bullet number table

Significado

La lista es una lista no numerada. La lista es una lista numerada. La lista es una tabla.

Los estilos b u l l e t y number deberían también incluir una o más etiquetas

<item> dentro de la etiqueta < l i s t > .

Cada etiqueta <item> se corresponde a un elemento de la lista. Cada etiqueta

<item> debería contener una etiqueta < d e s c r i p t i o n > , cuyo texto define el

texto de la lista de elementos:

/// <list type="bullet"> /// <item>

/// <description>Éste es el elemento 1.</description> /// </item>

/// <item>

/// <description>Éste es el elemento 2 . </description> /// </item>