Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

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

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#)

like image 338
Theo Lenndorff Avatar asked Jun 24 '09 11:06

Theo Lenndorff


People also ask

How to generate XML documentation in C#?

From the menu bar, choose Tools > Options to open the Options dialog box. Then, navigate to Text Editor > C# (or Visual Basic) > Advanced. In the Editor Help section, look for the Generate XML documentation comments option.

What is CREF in XML?

The cref attribute in an XML documentation tag means "code reference." It specifies that the inner text of the tag is a code element, such as a type, method, or property.

What sequence of characters indicates the start of an XML style documentation comment in C# code?

The use of XML doc comments requires delimiters that indicate where a documentation comment begins and ends. You use the following delimiters with the XML documentation tags: /// Single-line delimiter: The documentation examples and C# project templates use this form.

How do I read XML documents?

Just about every browser can open an XML file. In Chrome, just open a new tab and drag the XML file over. Alternatively, right click on the XML file and hover over "Open with" then click "Chrome". When you do, the file will open in a new tab.


1 Answers

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

like image 177
Adrian Lynch Avatar answered Oct 28 '22 13:10

Adrian Lynch