Is there a way of referencing the xml comments to avoid duplicating them?

Question

This is not a biggie at all, but something that would be very helpful indeed if resolved.

When I'm overloading methods etc there are times when the xml comments are exactly the same, bar 1 or 2 param names. I have to copy/paste the comments down to each overloaded method, where they are the same. Sometimes, however, this can cause misleading information about the method if I update one of them and forget to go back and copy/paste them to all others. If there are alot of overloaded methods, this can be very time consuming and prone to error.

So I'm wondering if there is a way of storing comments in one place (like a variable), which I can simply reference instead. This way, one change will be reflected across all related commetns.

Here's an example:

    /// <summary>
    /// Go and do something
    /// </summary>
    public void DoSomething()
    {
        DoSomething(true, "Done something");
    }

    /// <summary>
    /// Go and do something
    /// </summary>
    /// <param name="doIt">whether it should be done or not</param>
    public void DoSomething(bool doIt)
    {
        DoSomething(doIt, "Done something");
    }

    /// <summary>
    /// Go and do something cool
    /// </summary>
    /// <param name="doIt">whether it should be done or not</param>
    /// <param name="doneMessage">message to show once done</param>
    public void DoSomething(bool doIt, string doneMessage)
    {
        if (doIt)
            Console.WriteLine(doneMessage);
    }

So as you can see, all of the comments are the same except I decided to make a correction on the last one to read 'Go and do something cool'. Now i'll have to go and change this is all the other method comments too.

Cheers.

Answer 1

Yes, you can do this (tested in VS 2019 16.11) by using the <inheritdoc> tag with a cref attribute making sure you reference the appropriate "parent" overload.

So in your example you can reference the overload which has the most documentation and intellisense will use all it can from that method:

    /// <inheritdoc cref="DoSomething(bool, string)"/>
    public void DoSomething()
    {
        DoSomething(true, "Done something");
    }

    /// <inheritdoc cref="DoSomething(bool, string)"/>
    public void DoSomething(bool doIt)
    {
        DoSomething(doIt, "Done something");
    }

    /// <summary>
    /// Go and do something cool
    /// </summary>
    /// <param name="doIt">whether it should be done or not</param>
    /// <param name="doneMessage">message to show once done</param>
    public void DoSomething(bool doIt, string doneMessage)
    {
        if (doIt)
            Console.WriteLine(doneMessage);
    }

Answer 2

According to these specifications:

http://msdn.microsoft.com/en-us/library/5ast78ax.aspx

There is no set standard for XML comments; the ones shown on that page are just "recommended". In the recommended tags, there is no such feature. However, the XML documentation tool happily accepts the following with no warning:

/// <summary id="30">foo</summary>
void bar();

/// <summary id="30"/>
void bar(int baz);

Whether this is useful to you or not depends on what exactly you do with the XML file that the compiler spits out. Unfortunately, things like Intellisense (code completion and in-IDE tooltips, etc). won't do anything with it.

EDIT: Try out <include>, as described in http://msdn.microsoft.com/en-us/library/9h8dy30z.aspx . It's a bit heavyweight, because it requires a separate file, but if your documentation is enormous it could be worth it.