Documenting overloaded methods with the same XML comments

Question

Say I have this constructor:

/// 

/// Example comment.
/// 
public SftpConnection(string host, string username, 
    string passwo         


        

Answer 1

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>

Answer 2

You can’t really do this. I find it annoying too.

However, you can alleviate the problem by using default parameter values instead of lots of overloads. Instead of:

public SftpConnection(string host, string username, string password, int port)
public SftpConnection(string host, string username, string password)
public SftpConnection(string host, string username, int port)
public SftpConnection(string host, string username)

You can have just a single one:

public SftpConnection(string host, string username, string password = "",
                      int port = 22)

This has multiple advantages:

• Need only one XML comment. The whole point of my answer. ☺

• Users of Visual Studio can instantly see that the default value for port is 22. With the overloads, this is not obvious; you have to specifically mention it in the documentation.

• You indirectly encourage client code to become more readable by encouraging the use of named parameters (e.g. port: 2222 instead of just 2222, which is less clear).

And the greatest part about this is that using default values does not remove the ability to still have several overloads if you need them. Typical examples where you want overloads with default values might be something like...

ReadFrom(string filename, ReaderOptions options = null)
ReadFrom(Stream stream, ReaderOptions options = null)
ReadFrom(byte[] rawData, ReaderOptions options = null)

In these cases, I would argue the XML comments should actually be different.

Answer 3

Is this what you want?

/// <seealso cref="SftpConnection(string,string,string,int)"</seealso>

Answer 4

A half-solution is the <overloads></overloads> tag. While it doesn't solve the issue with <summary/>, it does provide documentation that shows up anywhere all the overloads are listed as a group, including both IntelliSense and SandCastle.