Referencing documentation comments (or parts thereof) in other classes/methods/fields

Question

Is it possible to tell Visual Studio to use the whole or part of the documentation comment of another class/field/method for the given class/field/method? It would be nice if in the following scenario,

public class Foo
{
    /// <summary>
    /// ... lots of text ...
    /// </summary>
    protected Foo(...arguments...) { ... }
}

public class Bar
{
    /// <summary>
    /// ... lots of text ...
    /// </summary>
    public Bar(...same arguments as in Foo...) { ... }
}

where the Bar constructor is supposed to have the exact same documentation comment as the Foo constructor, I do not always have to copy-paste the comment after I changed it.

It would be even nicer if in the following scenario,

class Blah
{

    ///<summary>
    ///describes a lot of things.
    ///</summary>
    private MyType stuff;

    ///<summary>
    ///Gets the stuff, which ~magic-reference-to-doc-comment-of-stuff
    ///</summary>
    public MyType Stuff => stuff;

}

the doc comment of property Stuff was "Gets the stuff, which describes a lot of things".

And it would be even even nicer if I in the following scenario,

///<summary> ... </summary>
///<param name="a">The a number.</param>
///<param name="b">The b number.</param>
///<param name="c">Oh, I see!</param>
public void Method1(int a, int b, int c) { ... }

///<summary> ... </summary>
///<param name="a">~magic-reference-to-param-description-of-a-in-Method1</param>
///<param name="d">~magic-reference-to-param-description-of-c-in-Method1</param>
public void Method2(int a, int d) { ... }

the param description for a in Method2 was "The a number." and the param description for d in Method2 was "Oh, I see!".

Can some of this be achieved, and if yes, how?

score 0 · Answer 1 · answered Oct 04 '22 at 16:58

This is somewhat possible via the <include> tag, and putting the shared documentation in a common location. The following example is copied from the linked MS docs. Imagine some .cs file with the following comment:

/// <include file="docs.xml" path='extradoc/class[@name="IntList"]/*' />
public class IntList { ... }

Then inside docs.xml:

<?xml version="1.0"?>
<extradoc>
    <class name="IntList">
        <summary>
            Contains a list of integers.
        </summary>
    </class>
    <class name="StringList">
        <summary>
            Contains a list of strings.
        </summary>
    </class>
</extradoc>

Referencing documentation comments (or parts thereof) in other classes/methods/fields

1 Answers1