用相同的 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 注释单行，这样它们使用完全相同的 cmets，这样我就不需要复制粘贴整个巨大的原始 cmets？

我在想类似：<use cref="SftpConnection(string,string,string,int)" /> 这当然行不通。

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

谢谢:-)

Answer 1

你真的不能这样做。我也觉得很烦。

但是，您可以通过使用默认参数值而不是大量重载来缓解此问题。而不是：

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 的用户可以立即看到 port 的默认值为 22。对于重载，这并不明显；您必须在文档中特别提及。

• 您通过鼓励使用命名参数间接鼓励客户端代码变得更具可读性（例如，port: 2222 而不是仅仅2222，这不太清楚）。

最重要的是，使用默认值不会删除在需要时仍然有多个重载的能力。您希望使用默认值进行重载的典型示例可能类似于...

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

在这些情况下，我认为 XML cmets 实际上应该是不同的。

Answer 2

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

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

/// <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 3

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

Answer 4

这是你想要的吗？

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

Answer 5

我来自谷歌，我想根据上面的讨论分享我的解决方案。

假设你有两个方法，其中一个是重载：

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

为了将它们映射到 XML 文件文档，您需要使用以下注释：

/// <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);

在您的 XML 文件中，您需要使用 @Kache 告知的 <overloads> 标签，唯一需要注意的是需要尊重的层次结构，所以最终的解决方案就像这个：

在 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>