如何用相同的 XML 注释记录重载方法？

Question

我知道有这样的问题，但它们已经过时了。所以我正在创建一个新的。

目前有 3 个重载方法我必须这样做：

/// <summary>
/// Description that described summary of an overloaded method.
/// </summary>
/// <param name="fileName">Description that describes filename parameter</param>
/// <param name="options">Description that describes options parameter</param>
/// <returns>Description of what method returns</returns>
public bool ReadFrom(string fileName, ReaderOptions options = null) {
    return false;
}

/// <summary>
/// Description that described summary of an overloaded method.
/// </summary>
/// <param name="stream">Description that describes stream parameter</param>
/// <param name="options">Description that describes options parameter</param>
/// <returns>Description of what method returns</returns>
public bool ReadFrom(Stream stream, ReaderOptions options = null) {
    return false;
}

/// <summary>
/// Description that described summary of an overloaded method.
/// </summary>
/// <param name="rawData">Description that describes rawData parameter</param>
/// <param name="options">Description that describes options parameter</param>
/// <returns>Description of what method returns</returns>
public bool ReadFrom(byte[] rawData, ReaderOptions options = null) {
    return false;
}

我想要这样的东西：

#region overloadedReadFromMethods
/// <summary>
/// Description that described summary of an overloaded method.
/// </summary>
/// <param name="fileName">Description that describes filename parameter</param>
/// <param name="options">Description that describes options parameter</param>
/// <returns>Description of what method returns</returns>
public bool ReadFrom(string fileName, ReaderOptions options = null) {
    return false;
}

/// <param name="stream">Description that describes stream parameter</param>
public bool ReadFrom(Stream stream, ReaderOptions options = null) {
    return false;
}

/// <param name="rawData">Description that describes rawData parameter</param>
/// <returns>Even considering that returns tag is present on the first overloaded method,
/// this overloaded method shows this specific description.
/// </returns>
public bool ReadFrom(byte[] rawData, ReaderOptions options = null) {
    return false;
}
#endregion overloadedReadFromMethods

所以第一个重载的方法描述了默认描述，然后下面的方法可以用自己的描述覆盖它。我希望它显示在 Visual Studio 的 IntelliSense 中。

Answer 1

我认为记录每种方法的额外工作是必要的，因为它们都有不同的签名。方法有不同<param></param>

InheritDoc是一个可以用来继承xml文档的包。

Answer 2

TLDR - 这是不可能的

长话短说，就像过去一样，您仍然不能以这种方式重用 cmets。

Some interesting ideas here

1. 使用可选参数创建一个函数。虽然这会缓解问题，但我发现可选参数有时本身并不方便，因为它们使内部逻辑过于复杂并使单元测试变得非常困难。在你的情况下重载是有道理的，所以这个解决方案不适用。

2. 使用<overloads> 注释。我在官方文档中看不到它

3. 使用<see>和<seealso> xml标签来使用参考

使用<include> 标签

这仍然不是一个解决方案，但它允许您拥有单独的 xml 文档并进行整体处理。 include documentation