How to make source code a part of XML documentation and not violate DRY?

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! ;)

Answer 2

Why not go with a more standard approach for documenting the code by using fields like

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

Just a thought.

Answer 3

To me the main purpose of the comments is to describe the code. copy and pasting the code will not fullfill that purpose, so I guess my question ould be "What's the intended purpose of the documentation?" Do you wish to document what the method does to some one calling the method+ (kinda like API documentation) or do you what to document how the method works so that another developer can maintain the source code? or something different?

If it's the first I would use the code at all. I would state that the method calculates the fee taking into account the different rules for discounts and whatelse is included in the algorithm. The business rules for those calculation is in an API context not an important information, they might very well change with out the API changing (only the implementation behind the interface would change)

If it's the second purpose repeating the code will still not fullfill the purpose. Repeating something does make it any clearer, repeating something does make it any clearer, but an example of how to use the method might help explain. A usage example will not be a repetition and will only need to be changed if the method signature changes and then a changes in the documentation would be required anyways

Answer 4

You may want to play around with the include element. I've never used it, so I don't know whether you can mix that element with the other, regular XML Comment elements, but the the way I read the (sparse) documentation, it doesn't look like it.

While that would be the best option, even if that's not possible, you might be able to combine usage of that element with a script that finds the relevant pieces of code and inserts it into the XML file.

I'd probably take another route, though. Since the output of XML Comments is just an XML file, you can process it after it has been created, but before running Sandcastle on it. I would then make another script that looks for all the code that needs to go into the help file, and extract that to a separate XML file.

These two XML files can then be merged using XSLT and passed on to SandCastle.

How would you identify code that needs to go into the help file? Off the top of my head, I can think of three options:

• Attributes
• Regions
• Comments

Personally, I'd prefer Attributes.

On a closing note I'd like to point out that while this is certainly possible, it's probably more work than just copying and pasting and keeping a bit of discipline :)