Primero comenzemos con los tipos de comentarios que se pueden emplear en C#
Tenemos 3 tipos:
A)) Comentarios de una linea: //
Ejemplo:
//comentario
int a = 1; //otro comentario
B)) Comentario de varias lineas: /* */
Ejemplo:
/* comentario
* de varias
* líneas */
C)) Comentario de plantilla de documentacion: ///
Esos tres slashes ///
se usan para crear una plantilla de un comentario de documentación, la cual luego puede generar documentacion automaticamente, es util para:
1) Mostrar informes XML.
2) Dar ayudas al autocompletar el nombre o parámetros de la clase, objeto, variable, etc
3) Generar la propia documentación del programa basada exclusivamente en estos comentarios.
///<summary>
///summary description
///</summary>
///<remarks>
///This is a test.
///</remarks>
Es decir que con esa etiqueta /// todo los comentarios que agregues y les añadas las correspondientes etiquetas generaran un XML con un formato de documentado.
En otras palabras es como hacer un codigo HTML pero con las especificaciones del codigo, como variables, objetos, clases, las cuales tendran un formato especifico dentro del XML
Ejemplos:
Documentar clases
///<summary>
///Clase principal de la aplicación.
///</summary>
///<remarks>
///Lee archivos de configuración y crea los hilos que ejecutan el resto del programa.
///</remarks>
class CApp {
static void Main(string[] args) {
...
}
}
Entre las etiquetas <summary>
y </summary>
ponemos la descripción o resumen de la clase. Las etiquetas <remarks>
y </remarks>
las usamos para comentarios especiales, no se verán en el autocompletado pero sí en la documentación.
Documentar miembros
class CApp2 {
///<summary>
///Variable que almacena el número de reintentos al acceder a un archivo.
///</summary>
///<remarks>
///Puede ser modificada en cualquier momento.
///</remarks>
int var = 1;
...
}
Documentar métodos/funciones
///<summary>
///Lee la configuración de la aplicación desde el disco.
///</summary>
///<return>
///Devuelve true si la configuración fue leida. Si hubo algún error se devuelve false.
///</return>
///<param name="archivo">
///Ruta del archivo en disco a leer.
///</param>
public bool LeeConfig(string archivo) {
bool c = false;
...
return c;
}
Entre las etiquetas <return>
y </return>
se explica el valor devuelto por la función, y las etiquetas <param></param>
se utilizan para describir cada uno de los parámetros del método/función.
Generar documentación
A parte de las ayudas al autocompletado que aparecen automaticamente en Visual Studio, SharpDevelop y MonoDevelop al documentar el código, también se pueden generar archivos de documentación.
En Windows, usando la implementación del .NET Framework hecha por Microsoft, se utiliza el siguiente comando:
C:\>csc /doc:Documentacion.xml Programa.cs
Con esto podras generar tu documentacion del sistema en formato XML
Ejemplo:
CODIGO C#:
// compile with: /doc:DocFileName.xml
/// text for class TestClass
public class TestClass
{
/// <summary>DoWork is a method in the TestClass class.
/// <para>Here's how you could make a second paragraph in a description. <see cref="System.Console.WriteLine(System.String)"/> for information about output statements.</para>
/// <seealso cref="TestClass.Main"/>
/// </summary>
public static void DoWork(int Int1)
{
}
/// text for Main
static void Main()
{
}
Generara este XML:
<?xml version="1.0"?>
<doc>
<assembly>
<name>YourNamespace</name>
</assembly>
<members>
<member name="T:DotNetEvents.TestClass">
text for class TestClass
</member>
<member name="M:DotNetEvents.TestClass.DoWork(System.Int32)">
<summary>DoWork is a method in the TestClass class.
<para>Here's how you could make a second paragraph in a description. <see cref="M:System.Console.WriteLine(System.String)"/> for information about output statements.</para>
<seealso cref="M:DotNetEvents.TestClass.Main"/>
</summary>
</member>
<member name="M:DotNetEvents.TestClass.Main">
text for Main
</member>
</members>
</doc>
Si te interesa mas sobre los INFORMES DE CODIGO:
Citando a https://msdn.microsoft.com/es-ve/library/aa291781(v=vs.71).aspx
Crear informes de código
Visual Studio .NET 2003
Una vez definidos los objetos y las interfaces de un proyecto, puede
ver la estructura de dichos objetos e interfaces, así como la
estructura de los miembros, mediante informes Web de comentario de
código. Estos informes muestran información sobre las definiciones del
código en una serie de páginas .htm. Si utiliza C# u otros lenguajes
que admiten comentarios de documentación XML, puede utilizar estos
comentarios para ofrecer descripciones resumidas, comentarios de la
forma en que se comporta una definición o resúmenes de parámetros para
funciones.
Nota Visual C++ proporciona compatibilidad limitada para comentarios
de documentación XML. Los informes Web de comentarios de código
reconocen las siguientes etiquetas XML:
<summary></summary>
Describe un miembro para un tipo.
<remarks></remarks>
Especifica información general de una clase u otro tipo.
<param></param>
Se utiliza en el comentario de una declaración de método para describir uno de los parámetros del método.
<returns></returns>
Se utiliza en el comentario de una declaración de método para describir el valor devuelto.
<newpara></newpara>
Inicia un nuevo párrafo en los comentarios.
Para obtener más información de las otras etiquetas y de estas,pero en mayor profundidad: https://msdn.microsoft.com/es-ve/library/aa288210(v=vs.71).aspx