How to make source code part of XML documentation, rather than violate DRY?

Question

I would like to add portions of the source code to the XML documentation. I could copy and paste the source code into some <code> elements, for example:

/// <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 ways to add source code to XML documentation in C #?

I am processing XML documentation using Sandcastle and want to make a technical help file (* .chm) out of it. I would like to add parts or full bodies of methods to the help file.

---

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

Suppose I have a 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 add information on how the board is calculated in the technical assistance file.

The most obvious solution would be to write the algorithm as a prosaic text in a comment like: "If the account has a total of less than 5000, then ...".

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

Both solutions violate the DRY principle! I would like to add the method body or part of the method body to the help file without duplicating the information.

Is this possible in C #? (I think that RDoc for Ruby is able to do this, but I need some solution in C #)

Answer 1

Just throwing an idea there ...

Automate a process that somehow restricts blocks of code, and then embed this code in an 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 this is not very, but this is the beginning!;)

Answer 2

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

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

Just a thought.

Answer 3

For me, the main purpose of comments is to describe the code. copying and pasting the code will not completely fill this goal, so I think my question should be "What is the goal of the documentation?" Do you want to document what the method does with whoever calls the + method (for example, as API documentation), or can you document how this method works so that another developer can maintain the source code? or something different?

If this is the first, I would use the code at all. I would say that the method calculates the fee taking into account various discount rules and whatelse is included in the algorithm. The business rules for these calculations in the context of the API are not important information, they can change very well with changing the API (only the implementation behind the interface will change)

If this is the second target repeating the code, it still will not completely fill the target. Repeating something makes it clearer, repeating something makes it clearer, but an example of how to use this method can help explain. The usage example will not be a repetition, and it will need to be changed only if the signature of the method changes, and in any case changes to the documentation are required.

Answer 4

You might want to play around with the include element . I never used it, so I don’t know if this element can be mixed with other regular elements of the XML comment, but as I read the (sparse) documentation, it doesn’t look like it.

Although this will be the best option, even if this is not possible, you can combine the use of this element with a script that finds the appropriate code fragments and inserts it into an XML file.

I would choose another route. Since the output of XML comments is just an XML file, you can process it after it is created, but before running Sandcastle on it. Then I will make another script that looks for all the code that should go into the help file and extract it into a separate XML file.

These two XML files can then be combined using XSLT and transferred to SandCastle.

How would you define the code that should go into the help file? From head to toe I can imagine three options:

• The properties
• Regions
• Comments

Personally, I would prefer Attributes.

In a final note, I would like to point out that although it is certainly possible, it is probably more work than just copying and pasting and maintaining discipline :)