Documentación: Referencia

RaraAvis
Resultado de imagen de documentación codigo

Simplemente usando el comentario triple /// en la cabecera de una estructura de código (clase, método,…) automáticamente se generará la base del comentario, como dato adicional los namespaces no se pueden comentar.

Estos comentarios que generemos se guardarán en ficheros XML, por lo tanto al comentar hay que tener en cuenta que algunos caracteres pueden dar error, por ejemplo ‘<’ se convierte en < y ‘>’ se convierte en &gt;

También comentar que algunas de las etiquetas que se van a explicar pueden no mostrarse correctamente a través de IntelliSense pero si se verán correctamente en la documentación final.

Uso de enlaces

Cualquier etiqueta de documentación es susceptible de usar el atributo cref, este atributo tiene ciertas características para hacer referencia a otros elementos de código como se verá más adelante, por ejemplo para agregar una referencia a un tipo genérico usaríamos:

<see cref="Robot{T}" />

La lista a continuación son prefijos que se pueden agregar para especificar el tipo de código al que se hace referencia, si está bien referenciados no hace falta ya que el compilador lo agrega automáticamente, dependiendo del tipo de enlace se usará un prefijo u otro:

ClaveDescripción
N Namespace
T Tipo: clase, interfaz, estructura, enumerado, delegado
F Campo
P Propiedad
M Método (incluyendo constructores, operadores,…)
E Evento
¡ Cadena de error, generado por el compilador cuando hay un error

Por ejemplo, para un tipo se podría usar:

<see cref="nCubed.Core.Exceptions.SemanticException"/>

En caso de que se haga una referencia a código de .NET, para que Sandcastle lo encuentre correctamente se haría así:

<see cref="T:System.Func`1"/> to be processed.

También se puede usar para hacer referencia a un método de una interfaz genérica:

<see cref="nCubed.Core.Expressions.IAnyEnumerableCollection`1.Any"/>

Si hay dos parámetros genéricos se haría:

<see cref="nCubed.CQRS.Infrastructure.ProcessManagerRepository`2"/>

Cuando se hace referencia a métodos

<see cref="M:System.Object.Equals(System.Object)"/>

Referencia

A continuación la referencia de las etiquetas disponibles, todas las etiquetas se explican con la misma estructura:

  • Nombre de la etiqueta.
  • Descripción.
  • Ejemplo de sintaxis.
  • Imagen de ejemplo del resultado en documentación en línea creada con SandCastle (muy similar a MSDN) y en Visual Studio si aplica.

<summary>

Describe un tipo o miembro del mismo. Este texto es el único origen de información para IntelliSense, y se muestra también en Object Browser Window. Admite también el atributo cref. Es el elemento por defecto que aparece al empezar la documentación con ///

/// <summary>
/// Base constructor por person object.
/// </summary>

<c> <code>

El texto indicado representa código y se representará como tal, con el estilo de letra para código, si se usa <code> aparecerá encuadrado. Ejemplo:

/// <summary> 
/// Name used for <c>Person</c> object. 
/// It can be used as <code> Person p = new Person(); </code>
/// </summary>

<example>

Crea un ejemplo para la documentación, si es para crear un ejemplo de código es recomendable usarlo junto con la etiqueta <code>.

/// <example>
/// It defines a SecondName for the user, 
/// it is used normally with <c>Name</c> as 
/// <code>string s = Name + SecondName;</code>
/// </example>

<exception>

Sirve para indicar que excepciones se lanzarán, se puede usar con métodos, propiedades, eventos e índices. Se puede usar el atributo cref que permite indicar una referencia a una excepción.

/// <exception cref="ArgumentNullException">
/// Returns error if <c>Name</c> is null.
/// </exception>

<include>

Permite incluir comentarios adicionales en otro archivo, esto es útil para poder usar varios ficheros a la vez y no incluir los comentarios directamente en código.

Se usan los siguientes atributos: file con el nombre del fichero adicional y path con la ruta XPath al comentario de código.

Al compilar el contenido el fichero referenciado se incrusta en la sección que hace la referencia como si se hubiera escrito directamente.

A través de XPath accedemos a la estructura xml que contiene la documentación propiamente dicha en el formato esperado. Un ejemplo de sintaxis es:

<include file='filename' path='tagpath[@name="id"]' />

Y si creamos un documento XML como:

<?xml version="1.0"?>
<CustomDoc>
    <CustomMember name="Animal">
	<summary>
		Full documentation for Animal class.
	</summary>
    </CustomMember>
</CustomDoc>

Tendríamos este resultado:

/// <include file='Docs/AnimalInclude.xml'
/// path='CustomDoc/CustomMember[@name="Animal"]/*'/>

<list>

Permite crear una lista, el elemento <list> admite varios valores bullet/number/table cada uno de los cuales genera la lista en un formato diferente, no numerada, numerada o en formato tabla. Solo si se usa la opción table tiene sentido usar la etiqueta listheader, term y description se pueden considerar como una etiqueta del estilo clave/valor. 

/// <summary>
/// It defines a person completely.
/// <list type="table">
/// <listheader>
/// <term>Person</term>
/// <description>Different people.</description>
/// </listheader>
/// <item>
/// <term>Normal.</term>
/// <description>Person from this planet.</description>
/// </item>
/// </list>
/// </summary>

<para>

Se usa dentro de otras etiquetas como <summary> <remarks> <returns>  para agregar estructura al código, como crear párrafos.

/// <summary>
/// Duplicates the name.
/// <para>Generally it is not useful, 
/// but for any person people love it.</para>
/// </summary>

<param>

Sirve para agregar información al parámetro de una función.

/// <param name="secondName">
/// The second name to append.
/// </param>

<paramref>

El nombre de parámetro al que se quiere hacer referencia, es útil para indicar en etiquetas <summary> o <remarks>, por defecto en Sandcastle aparece en cursiva.

/// Clones a person with the 
/// <paramref name="name">supplied
/// </paramref>.

<typeparam>

Sirve para comentar un tipo genérico o describir un parámetro de tipo. Se agrega una etiqueta para cada parámetro de tipo. El texto se mostrará en IntelliSense, y en Object Browser Window.

/// <typeparam name="T">
/// Type for the array, must be <c>Person</c>
/// </typeparam>

<permission>

Útil para documentar el acceso a un miembro, hay que indicar la clase que gestiona el acceso, para esto se usa habitualmente la clase PermissionSet.

/// <permission cref="System.Security.PermissionSet">
/// Everyone can access this method.
/// </permission

<remarks>

Se usa para agregar información adicional sobre un tipo, proporcionando más  información que la suministrada por <summary>. Esta información se muestra en Object  Browser Window.

/// <remarks> 
/// This is a critical class due to his abstract aspect. 
/// </remarks>

<returns>

Representa el valor devuelto por la función.

/// <returns>
/// Name concatenated itself.
/// </returns>

<see>

Permite especificar un enlace dentro de un texto, el atributo cref permite crear hipervínculos a páginas de documentación.

/// <see 
/// cref="System.Console.WriteLine(System.String)"/>
/// to write to console.

<seealso>

Para indicar el texto que se mostrará en la sección See Also.

/// <summary>
/// Overrides original, 
/// <seealso cref="Person.GetHashCode()"/>.
/// </summary>

<value>

Describe el valor que representa una propiedad.

/// <value>
/// The Address property must not contain extended chars.
/// </value>

Referencias

Recommended Tags for Documentation Comments:
https://msdn.microsoft.com/es-es/library/5ast78ax.aspx
How to: Use the XML Documentation Features (C# Programming Guide)
https://msdn.microsoft.com/es-es/library/z04awywx.aspx

Documentación: Referencia