Comment faire du code source une partie de la documentation XML et ne pas violer DRY?

Question

Je voudrais ajouter des parties du code source à la documentation XML. Je pourrais copier & coller le code source à un code < > éléments, comme celui-ci:

/// <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(); 
} 

Le maintien de ce sera douloureux. Existe-t-il d'autres possibilités pour ajouter du code source à la documentation XML en C#?

Je suis en train de traiter la documentation XML avec Sandcastle et je voudrais en faire un fichier d'aide technique (* .chm). Je voudrais ajouter des parties ou compléter des corps de méthode à ce fichier d'aide.

---

EDIT: Merci pour le commentaire de slide_rule. J'ai ajouté un exemple plus réaliste et moins trivial:

Supposons que j'ai une méthode comme ceci:

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; 
    } 
} 

Il serait agréable d'avoir la possibilité d'ajouter les informations comment la taxe est calculée dans la technique fichier d'aide.

La solution la plus évidente serait d'écrire l'algorithme comme un texte prosaïque dans le commentaire comme: "Si la facture a une somme totale inférieure à 5000 alors ...".

Une autre solution serait de copier & coller le corps de la méthode dans le champ de commentaire et le mettre dans un <code> élément. Ce corps de méthode peut être compris assez facilement, même sans beaucoup de connaissances sur C# - donc il n'y a rien de mal à le mettre dans un fichier d'aide technique.

Les deux solutions violent le principe DRY! Je voudrais ajouter des corps de méthode ou des parties d'un corps de méthode dans le fichier d'aide, sans dupliquer les informations.

Est-ce possible en C#? (Je pense que RDoc pour Ruby est capable de le faire, mais je dois une solution en C#)

Answer 1

Juste jeter une idée là-bas ...

Automatiser un processus qui ressemble à des blocs de code délimités d'une certaine façon, Puis injectez ce code dans le commentaire 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 
} 

Je sais que ce n'est pas joli, mais c'est un début! ;)

Answer 2

Pourquoi ne pas aller avec une approche plus standard pour documenter le code en utilisant des champs comme

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

Juste une pensée.

Answer 3

Pour moi, le but principal des commentaires est de décrire le code. copier et coller le code ne remplira pas ce but, donc je suppose que ma question serait "Quel est le but de la documentation?" Souhaitez-vous documenter ce que la méthode fait à quelqu'un qui appelle la méthode + (un peu comme la documentation de l'API) ou savez-vous documenter le fonctionnement de la méthode afin qu'un autre développeur puisse maintenir le code source? ou quelque chose de différent?

Si c'est le premier, j'utiliserais le code du tout. Je dirais que la méthode calcule la redevance en tenant compte des différentes règles pour les remises et whatelse est inclus dans l'algorithme. Les règles métier pour ces calculs sont dans un contexte d'API pas une information importante, elles pourraient très bien changer sans changement d'API (seule l'implémentation derrière l'interface changerait)

Si c'est le deuxième but, répéter le code sera toujours pas remplir le but. Répéter quelque chose le rend plus clair, répéter quelque chose le rend plus clair, mais un exemple de la façon d'utiliser la méthode peut aider à expliquer. Un exemple d'utilisation ne sera pas une répétition et n'aura besoin d'être modifié que si la signature de la méthode change et qu'une modification de la documentation sera nécessaire de toute façon.

Answer 4

Vous voudrez peut-être jouer avec le include element. Je ne l'ai jamais utilisé, donc je ne sais pas si vous pouvez mélanger cet élément avec les autres éléments de commentaires XML réguliers, mais la façon dont je lis la documentation (clairsemée), il ne ressemble pas à ça.

Bien que ce soit la meilleure option, même si ce n'est pas possible, vous pourriez combiner l'utilisation de cet élément avec un script qui trouve les morceaux de code pertinents et les insère dans le fichier XML.

Je prendrais probablement un autre chemin, cependant. Puisque la sortie des commentaires XML est juste un fichier XML, vous pouvez le traiter après qu'il a été créé, mais avant d'y lancer Sandcastle. Je voudrais alors faire un autre script qui cherche tout le code qui doit aller dans le fichier d'aide, et l'extraire dans un fichier XML séparé.

Ces deux fichiers XML peuvent ensuite être fusionnés à l'aide de XSLT et transmis à SandCastle.

Comment identifiez-vous le code devant être placé dans le fichier d'aide? Du haut de ma tête, je peux penser à trois options:

• Attributs
• Régions
• Commentaires

Personnellement, je préfère les attributs.

Sur une note de conclusion, je voudrais souligner que tout cela est certainement possible, il est probablement plus de travail que simplement copier-coller et de garder un peu de discipline :)