Escritura de documentación para proyectos C#: de la A a la Z

¿Por qué es necesaria una documentación de calidad para proyectos C#?

La documentación es el puente entre el desarrollador y el usuario de su código. En el mundo de C# (.NET), este puente se construye con comentarios XML y herramientas especializadas (DocFX, Sandcastle). Una buena documentación:

• Acelera la incorporación de nuevos desarrolladores al proyecto
• Reduce la cantidad de preguntas en chats y tickets
• Mejora la calidad del código (involuntariamente refactoriza métodos deficientes al escribir la documentación)
• Genera automáticamente una referencia de API (IntelliSense en Visual Studio)

En este artículo, analizaremos el ciclo completo: desde la configuración del proyecto hasta la publicación de la documentación en un sitio estático. Todos los ejemplos están en C# (.NET 8).

1. Comentarios XML: la base de la documentación en C#

1.1. Cómo habilitar la generación del archivo XML

Visual Studio (o Rider) crea automáticamente un archivo XML con comentarios si se habilita la opción correspondiente en .csproj:

<PropertyGroup>    <GenerateDocumentationFile>true</GenerateDocumentationFile>    <DocumentationFile>bin\\$(Configuration)\\$(TargetFramework)\\$(AssemblyName).xml</DocumentationFile></PropertyGroup>

Después de la compilación, aparecerá un archivo XML con sus comentarios en la carpeta bin/Debug/net8.0/. Este archivo es la materia prima para DocFX y Sandcastle.

1.2. Etiquetas XML principales

Para escribir documentación de proyectos C#, utilice las siguientes etiquetas:

• <summary> — descripción breve de la clase, método o propiedad.
• <param name="..."> — descripción del parámetro del método.
• <returns> — descripción del valor devuelto.
• <exception cref="..."> — qué excepciones puede lanzar el método.
• <example> — ejemplo de uso.
• <see cref="..."> — enlace a otro tipo o método.
• <code> — código formateado dentro de la descripción.

1.3. Ejemplo de comentario completo

/// <summary>/// Realiza una división segura de dos números con verificación de cero./// </summary>/// <param name="dividend">Dividendo (numerador).</param>/// <param name="divisor">Divisor (denominador). No puede ser igual a 0.</param>/// <returns>Resultado de la división como fracción decimal.</returns>/// <exception cref="DivideByZeroException">Se lanza si divisor es igual a 0.</exception>/// <example>/// <code>/// double result = SafeDivider.Divide(10, 3);/// Console.WriteLine(result); // 3.333.../// </code>/// </example>public static double Divide(double dividend, double divisor){    if (divisor == 0)        throw new DivideByZeroException("La división por cero no está permitida.");    return dividend / divisor;}

Consejo: Escriba los comentarios en español si el proyecto es interno, o en inglés para una API pública. Lo importante es mantener un estilo uniforme.

2. Herramientas de generación de documentación: DocFX vs Sandcastle

2.1. DocFX (recomendado)

DocFX es una herramienta moderna de Microsoft que, a partir de comentarios XML y archivos Markdown adicionales, genera un sitio estático. Es compatible con C#, VB.NET e incluso JavaScript.

Instalación:

dotnet tool install -g docfx

Inicio rápido:

docfx init -o my-docscd my-docsdocfx builddocfx serve _site

DocFX automáticamente:

• Escanea sus archivos .csproj y .sln
• Extrae los comentarios XML
• Crea páginas para cada clase, método y propiedad
• Añade navegación, búsqueda y temas atractivos (por defecto, Bootstrap)