Documenting overloaded methods with the same XML comments

user_395126 0
Viewed 9066

Say I have this constructor:

/// <summary>
/// Example comment.
/// </summary>
public SftpConnection(string host, string username, 
    string password, int port) {...}

which has these overloads:

public SftpConnection(string host, string username, string password) 
    : this(host, username, password, 22) { }

public SftpConnection(string host, string username, int port) 
    : this(host, username, "", port) { }

public SftpConnection(string host, string username) 
    : this(host, username, "", 22) { }

and in reality, the XML comment is pretty large, with param, example and exception elements and so on.

Is there some way to add a special XML comment one-liner to the overloads, such that they use the exact same comments so that I don't need to copy-paste the whole, enormous original comments?

I'm thinking something like: <use cref="SftpConnection(string,string,string,int)" /> which doesn't work of course.

I am aware of the include element, but I get the impression it reads the comments from an XML file instead, which I don't want - I want the comment to still be visible in the code, but only once.

Thanks :-)

xmldocument overloading documentation xml c#
5 Answers

InheritDoc works perfectly for overloads (at least in VS 2019). You can override any part of it too. Official documentation says:

Inherit XML comments from base classes, interfaces, and similar methods.

/// <summary>
/// Method does something
/// </summary>
/// <param name="someString">Some string</param>
public void SomeMethod(string someString)
{
}

/// <param name="someInt">Some int</param>
/// <inheritdoc cref="SomeMethod(string)"/>
public void SomeMethod(string someString, int someInt)
{
}

/// <summary>Override the summary part</summary>
/// <param name="someString">Description for someString overridden</param>
/// <param name="anotherInt">Another int</param>
/// <inheritdoc cref="SomeMethod(string, int)"/>
public void SomeMethod(string someString, int someInt, int anotherInt)
{
}

/// <typeparam name="TOtherType">Other type</typeparam>
/// <inheritdoc cref="IInterface{TModel,TKey}.SomeMethod{TType}(TType)"/>
public void SomeMethod<TType, TOtherType>(TType first, TOtherType second)
{
}
user_31537120

I came from google and I'd like to share my solution based on the discussion above.

Let's assume that you have two methods, one of them is an overload:

public void MethodA(string paramA);
public void MethodA(string paramA, string paramB);

in order to map them to a XML file documentation you'd need to use the following commments:

/// <include file='Docs/MyXMLFile.xml' path='docs/members/MethodA/*'/>
public void MethodA(string paramA);

/// <include file='Docs/MyXMLFile.xml' path='docs/members/MethodA/*'/>
public void MethodA(string paramA, string paramB);

And inside of your XML file, you need to use the <overloads> tag as informed by @Kache, the only thing which is important to note is the hierarchical structure which needs to be respected, so the final solution would be like this:

in the MyXMLFile.xml

<overloads>
<MethodA>
      <summary>
       My MethodA...  
      </summary>
      <param name="paramA">
        My ParamA....
      </param>
</MethodA>
<MethodA>
      <summary>
       My MethodA...  
      </summary>
      <param name="paramA">
        My ParamA....
      </param>
      <param name="paramB">
        My ParamB....
      </param>
</MethodA>
</overloads>
user_43641570
Related