4

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?

Daniël Tulp
  • 1,745
  • 2
  • 22
  • 51
  • What if you use a [snippet](https://learn.microsoft.com/en-us/visualstudio/ide/walkthrough-creating-a-code-snippet?view=vs-2019) to store these duplicate information? – Jiale Xue - MSFT Nov 05 '21 at 09:23
  • than this would only be available for one developer and not the entire team (or you constantly need to import snippets from developers when someone adds a new ont) and if you wanted to change them after using them on several places, you would need to change all the snippets and do a search replace for the ones that were already used – Daniël Tulp Nov 06 '21 at 15:53

1 Answers1

4

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)
Peter Macej
  • 4,831
  • 22
  • 49
  • 1
    Thanks for your detailed answer, especially the first option seems usable, but I do foresee problems, for instance when a MethodZ is used in a completely different namespace, and I cannot refer to the namespace of MethodX as I would get a circular reference. The most centralized option is with the XML file as comment store, but this is not really user friendly. If these are all the possibilities, than I am not a very happy developer – Daniël Tulp Nov 01 '21 at 19:09
  • I'm not aware of any other means. The problem with XML comments and circular references is not different than other common problems with circular references. For example, you want to use MethodX from MethodZ (why not if you want to use the comment from X in Z). There are ways how to solve it, for example, creating a separate assembly with MethodX, see https://stackoverflow.com/a/42288056/217666. This is nothing new and nothing special in regards to XML comments. – Peter Macej Nov 02 '21 at 07:50
  • I understand this of course, but what I really would like is something like a resource file for parameter descriptions in XML comments. I think this would be really useful. – Daniël Tulp Nov 02 '21 at 09:46