Is there an efficient way to handle repeating XML comments C# code in Visual Studio

Question

I am using Visual Studio for a couple of years now and we have always just written all the XML comments for our C# code manually.

But lately I recognize the need for a way to centrally maintain certain XML comments as they are repeated multiple times throughout our code.

For example we will have several methods that accept the same parameter as they call each other in sequence, passing down the variable.

Or we will use the same parameter (like a search date for version handling) on multiple completely separate locations.

/// <summary>
/// Get data by searchdate
/// </summary>
/// <param name="searchdate">The date to use while fetching the data</param>
public void MethodX(DateTime searchDate)
    // fetch something from somewhere by date
    var y = MethodY(searchDate);
}

/// <summary>
/// Get some more data by searchdate
/// </summary>
/// <param name="searchdate">The date to use while fetching the data</param>
public void MethodY(DateTime searchDate)
    // fetch something more from somewhere else by date
}

We cannot store them in a resource file, as you cannot use code inside XML tags (at least I think I can't).

Is there an efficient way of storing and maintaining these repeated parts in our XML comments?

Answer 1

You can use <inheritdoc> XML doc tag if you want to have your XML comment on just a single place and reuse it on other places. This tag is respected by VS Intellisense and also by the tools that can generate documentation out of your comments, such as VSdocman (I'm the author of it).

Your code could look like this:

/// <summary>
/// Get data by searchdate
/// </summary>
/// <param name="searchDate">The date to use while fetching the data</param>
public void MethodX(DateTime searchDate)
{
    // fetch something from somewhere by date
    MethodY(searchDate);
}

/// <summary>
/// Get some more data by searchdate
/// </summary>
/// <param name="searchDate"><inheritdoc cref="MethodX"/></param>
public void MethodY(DateTime searchDate)
{
    // fetch something more from somewhere else by date
}

An alternative version of the inheritdoc without param tag in MethodY:

/// <summary>
/// Get some more data by searchdate
/// </summary>
/// <inheritdoc cref="MethodX" select="/param[name='searchDate']"/>
public void MethodY(DateTime searchDate)

And if you want to store your XML comments at a central place, you can save them in an external XML file and link to them with <include> XML doc tag.

Something like (not tested):

/// <summary>
/// Get some more data by searchdate
/// </summary>
/// <include file="myXmlComments.xml" path="[@name='MyClass.MethodX']/param[name='searchDate']"/>
public void MethodY(DateTime searchDate)