¿Cómo hacer que el código fuente sea parte de la documentación XML y no violar DRY?

Question

Me gustaría agregar partes del código fuente a la documentación XML. Podría copiar el código fuente & pasta hasta cierto < código > elementos, como este:

/// <summary> 
/// Says hello world in a very basic way: 
/// <code> 
/// System.Console.WriteLine("Hello World!"); 
/// System.Console.WriteLine("Press any key to exit."); 
/// System.Console.ReadKey(); 
/// </code> 
/// </summary> 
static void Main() 
{ 
    System.Console.WriteLine("Hello World!"); 
    System.Console.WriteLine("Press any key to exit."); 
    System.Console.ReadKey(); 
} 

mantenimiento de esta va a ser doloroso. ¿Hay otras posibilidades para agregar código fuente a la documentación XML en C#?

Estoy procesando la documentación XML con Sandcastle y me gustaría hacer un archivo de ayuda técnica (* .chm) fuera de ella. Me gustaría agregar partes o completar los cuerpos del método al archivo de ayuda.

---

EDIT: Gracias por el comentario de slide_rule. He añadido un ejemplo más realista y menos trivial:

Supongamos que tengo algún método como este:

public decimal CalculateFee(Bill bill) 
{ 
    if (bill.TotalSum < 5000) return 500; 
    else 
    { 
     if (bill.ContainsSpecialOffer) return bill.TotalSum * 0.01; 
     else return bill.TotalSum * 0.02; 
    } 
} 

Sería bueno tener una posibilidad de agregar la información de cómo se calcula la cuota en la técnica archivo de ayuda.

La solución más obvia sería escribir el algoritmo como texto prosaico en el comentario como: "Si la factura tiene una suma total inferior a 5000, entonces ...".

Otra solución sería copiar & pegar el cuerpo del método en el campo de comentario y ponerlo en un < elemento de código >. Este cuerpo de método se puede entender con bastante facilidad, incluso sin mucho conocimiento sobre C#, por lo que no hay nada de malo en ponerlo en un archivo de ayuda técnica.

¡Ambas soluciones infringen el principio DRY! Me gustaría agregar cuerpos de método o partes de un cuerpo de método en el archivo de ayuda, sin duplicar información.

¿Es esto posible en C#? (Creo RDoc para Ruby es capaz de hacer esto, pero necesito un poco de solución en C#)

Answer 1

sólo tirar una idea por ahí ...

automatizar un proceso que busca bloques de código delimitados de alguna manera, luego, inserte ese código en el comentario XML.

/// <summary> 
/// Says hello world in a very basic way: 
/// <code> 
///  Code block 1 
/// </code> 
/// </summary> 
static void Main() 
{ 
    // Code block 1 start 
    System.Console.WriteLine("Hello World!"); 
    System.Console.WriteLine("Press any key to exit."); 
    System.Console.ReadKey(); 
    // Code block 1 end 
} 

Sé que no es bonita, ¡pero es un comienzo! ;)

Answer 2

Por qué no ir con un enfoque más estándar para documentar el código mediante el uso de campos como

<summary> 
    <description>Displays Hello World!</description> 
    <arguments>None</arguments> 
    <returns>None</returns> 
</summary> 

Es sólo una idea.

Answer 3

Para mí, el objetivo principal de los comentarios es describir el código. copiar y pegar el código no cumplirá ese propósito, por lo que supongo que mi pregunta debería ser "¿Cuál es el propósito de la documentación?" ¿Desea documentar qué le hace el método a alguien que llama al método + (algo así como la documentación de API) o qué documenta cómo funciona el método para que otro desarrollador pueda mantener el código fuente? o algo diferente?

Si es el primero, usaría el código. Yo diría que el método calcula la tarifa teniendo en cuenta las diferentes reglas de descuentos y whatelse está incluido en el algoritmo. Las reglas de negocio para esos cálculos están en un contexto API que no es información importante, podrían cambiar sin cambiar la API (solo cambiaría la implementación detrás de la interfaz)

Si es el segundo propósito repetir el código seguirá no cumplió el propósito. Repetir algo lo hace más claro, repetir algo lo hace más claro, pero un ejemplo de cómo usar el método podría ayudar a explicarlo. Un ejemplo de uso no será una repetición y solo será necesario cambiarlo si la firma del método cambia y luego se requerirán cambios en la documentación de todos modos

Answer 4

Es posible que desee jugar con el include element. Nunca lo he usado, así que no sé si puedes mezclar ese elemento con el otro, los elementos regulares de comentarios XML, pero la forma en que leo la documentación (escasa) no se ve así.

Si bien esa sería la mejor opción, incluso si eso no fuera posible, podría combinar el uso de ese elemento con una secuencia de comandos que encuentre las piezas de código relevantes y las inserte en el archivo XML.

Probablemente tomaría otra ruta. Como el resultado de XML Comments es solo un archivo XML, puede procesarlo después de que se haya creado, pero antes de ejecutar Sandcastle en él. Luego haría otro script que busque todo el código que necesita ir al archivo de ayuda y lo extraiga en un archivo XML separado.

Estos dos archivos XML se pueden fusionar usando XSLT y pasar a SandCastle.

¿Cómo identificaría el código que debe ir al archivo de ayuda? De la parte superior de mi cabeza, no puedo pensar en tres opciones:

• Atributos
• Regiones
• Comentarios

Personalmente, preferiría Atributos.

En una nota de cierre me gustaría señalar que, si bien esto es ciertamente posible, es probable que sea más trabajo que acaba de copiar y pegar, y mantener un poco de disciplina :)