C# XML Comment Reuse
I'm writing a C# class library with a number of classes with functions that do just about the same stuff. I need to provide XML comments about the function arguments in each class which are very detailed but the same in most cases. Is there a way of reusing XML comments so I don't have to repeat these XML argument definitions all over my assembly?
Here's an example of my classes:
public class IsodoseControl : TestModule
{
/// <summary>
/// Verify a control on Isodose dialog
/// </summary>
/// <param name="args"> **<-- WHAT I DON'T WANT TO KEEP REPEATING**
/// Arguments: [Property, Condition, Expected Value, Tolerance]
/// Properties: STATE, VALUE, LABEL
/// Conditions: Exists, DoesNotExist, IsEnabled, IsDisabled, ...
/// Expected Value (optional): blah blah
/// Tolerance (optional): blah blah blah
/// </param>
public VerifResult VerifyIsodoseControl(string[] args)
{
...
}
}
public class BeamControl : TestModule
{
/// <summary>
/// Verify a control on Beam dialog
/// </summary>
/// <param name="args"> **<-- WHAT I DON'T WANT TO KEEP REPEATING**
/// Arguments: [Property, Condition, Expected Value, Tolerance]
/// Properties: STATE, VALUE, LABEL
/// Conditions: Exists, DoesNotExist, IsEnabled, IsDisabled, ...
/// Expected Value (optional): blah blah
/// Tolerance (optional): blah blah blah
/// </param>
public VerifResult VerifyBeamControl(string[] args)
{
...
}
}
Thanks
"The <include> tag lets you refer to comments in another file that describe the types and members in your source code. "
You could reference the same file from both classes using <include> tags.
/// <include file='comments.xml' path='MyDocs/MyMembers[@name="test"]/*' />
class OneClass {}
/// <include file='comments.xml' path='MyDocs/MyMembers[@name="test"]/*' />
class DifferentClassWithTheSameFunctionality {}
This link provides some examples of using <include>: http://msdn.microsoft.com/en-us/library/9h8dy30z.aspx
I don't think there's anything in Visual Studio that will help you. Sandcastle has a tag, inheritdoc, that will let you inherit entire blocks of xml comments, or you might also define a sandcastle token that contains your param text, which would let you write something like
/// <summary>
/// Verify a control on Beam dialog
/// </summary>
/// <param name="args"><token>CommonParamInfo</token></param>
/// (...)
Sandcastle was designed specifically for API documentation, and might not be appropriate for your case, though.