使用相同的XML注释记录重载方法 [英] Documenting overloaded methods with the same XML comments

问题描述

说我有这个构造函数:

/// <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元素等等.

and in reality, the XML comment is pretty large, with param, example and exception elements and so on.

是否有某种方法可以在重载中添加特殊的XML注释单行，以便它们使用完全相同的注释，这样我就无需复制粘贴整个庞大的原始注释了?

Is there some way to add a special XML comment one-liner to the overloads, such that they use the exact same comments so that I don't need to copy-paste the whole, enormous original comments?

我在想类似<use cref="SftpConnection(string,string,string,int)" />这样的东西，当然不起作用.

I'm thinking something like: <use cref="SftpConnection(string,string,string,int)" /> which doesn't work of course.

我知道include元素，但是给人的印象是它从XML文件中读取注释，这是我不希望的-我希望注释在代码中仍然可见，但是仅一次.

I am aware of the include element, but I get the impression it reads the comments from an XML file instead, which I don't want - I want the comment to still be visible in the code, but only once.

谢谢:-)

推荐答案

您不能真正做到这一点.我也觉得很烦.

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)

您只能拥有一个:

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

这具有多个优点:

• 仅需要一个XML注释.我的回答的重点. ☺

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

Visual Studio用户可以立即看到port的默认值为22.您必须在文档中特别提及它.

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.

通过鼓励使用命名参数(例如，port: 2222而不是2222，后者不太清楚)，间接地鼓励客户端代码变得更具可读性.

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).

与此有关的最大部分是，使用默认值不会 not 删除您仍然需要几个重载的功能.您希望使用默认值重载的典型示例可能类似于...

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)

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

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

这篇关于使用相同的XML注释记录重载方法的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！