Question

I’d like to add parts of the source code to the XML documentation. I could copy & paste source code to some <code> elements, like this:

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

Maintaining this will be painful. Are there other possibilities to add source code to the XML documentation in C#?

I am processing the XML documentation with Sandcastle and would like to make a technical help file (*.chm) out of it. I would like to add parts or complete method bodies to the that help file.

---

EDIT:
Thanks for the comment from slide_rule. I have added a more realistic and less trivial example:

Suppose I have some method like this:

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

It would be nice to have a possibility to add the information how the fee is calculated into the technical help file.

The most obvious solution would be write down the algorithm as prosaic text into the comment like: “If the bill has a total sum less than 5000 then …”.

Another solution would be to copy & paste the body of the method into the comment field and put it into a <code> element. This method body can be understood quite easily, even without much knowledge about C# — so there is nothing wrong to put it into a technical help file.

Both solutions violate the DRY principle! I would like to add method bodies or pieces of a method body into the help file, without duplicating information.

Is this possible in C#? (I think RDoc for Ruby is capable of doing this, but I need some solution in C#)

Answer 1

Just throwing an idea out there…

Automate a process that looks for code blocks delimited in some way, then inject that code into the XML comment.

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

I know it’s not pretty, but it’s a start! 😉