使用相同的XML注释记录重载的方法

Question

说我有这个构造函数:

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

有这些重载:

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) { }

而在现实中,XML注释是相当大的,有param,example和exception元素等等.

有没有办法在重载中添加一个特殊的XML注释单行,这样他们就可以使用完全相同的注释,这样我就不需要复制粘贴整个巨大的原始注释了？

我想的是:<use cref="SftpConnection(string,string,string,int)" />当然不起作用.

我知道这个include元素,但我得到的印象是它从XML文件读取注释,我不想要 - 我希望注释仍然在代码中可见,但只有一次.

谢谢 :-)

Answer 1

InheritDoc非常适合重载（至少在 VS 2019 中）。您也可以覆盖它的任何部分。官方文档说：

从基类、接口和类似方法继承 XML 注释。

/// <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)
{
}

Answer 2

你真的不能这样做.我觉得它也很烦人.

但是,您可以通过使用默认参数值而不是大量重载来缓解此问题.代替:

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)

你可以只有一个:

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

这有多个优点:

• 只需要一条XML评论.我的答案的重点.☺

• Visual Studio的用户可以立即看到默认值为port22.对于重载,这并不明显; 你必须在文档中特别提到它.

• 您通过鼓励使用命名参数来间接鼓励客户端代码变得更易读(例如,port: 2222而不仅仅是2222,这不太清楚).

而这个最大的部分是使用默认值并不会删除仍然有几个重载如果你需要他们的能力.您希望使用默认值重载的典型示例可能类似于......

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

在这些情况下,我认为XML注释实际上应该是不同的.

Answer 3

半解决方案是<overloads></overloads>标签。虽然它不能解决 的问题<summary/>，但它确实提供了显示所有重载作为一个组列出的任何地方的文档，包括 IntelliSense 和 SandCastle。