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

Posted 2023-04-12

【中文标题】如何用相同的 XML 注释记录重载方法？

【英文标题】：How to document overloaded methods with the same XML comments?

【发布时间】：2020-04-22 20:23:24

【问题描述】：

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

目前有 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 中。

【参考方案1】：

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

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

【讨论】：

谢谢。安装额外的包对我来说不是问题。我正在记录它以供其他人将来使用（Github 存储库），并在我忘记时为我自己使用。他们可能不会在他们的个人电脑上安装它。我猜它对于编译的模块会很好地工作，但是对于没有 InheritDoc 的贡献者，它仍然不会显示重载的描述，对吧？

【参考方案2】：

TLDR - 这是不可能的

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

Some interesting ideas here

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

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

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

使用<include> 标签

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

【讨论】：

谢谢。我阅读了关于 、 和 的信息，但无法使其工作。我该如何使用这些？这些会帮助我避免以任何方式重复吗？也许至少我不必自己复制粘贴描述（标签之间的文本）。

你不会从中得到太多。检查docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/… 以查看用法。它只会显示包含类型的 make 可发现。

官方文档中没有看到重载，所以我不希望任何工作室改变任何东西，除了告诉用户检查 cmets 的其他重载。

大约 1。是的，这是我试图避免的：超级方法中的复杂逻辑。所以我不必做 public bool ReadFrom(string fileName ="", Stream stream = null, byte[] rawData = null, ReaderOptions options = null)。

你很不走运......我只会将包含标签用于打包的库，说实话......