Документирование перегруженных методов с теми же комментариями XML

Скажем, у меня есть этот конструктор:

/// <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, чего я не хочу - я хочу, чтобы комментарий все еще был видимым в коде, но только один раз.

Спасибо: -)

Ответы

Ответ 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 должны быть разными.

Ответ 2

Полурешением является тег <overloads></overloads>. Хотя это не решает проблему с <summary/>, она предоставляет документацию, которая отображается везде, где все перегрузки перечислены как группа, включая как IntelliSense, так и SandCastle.

Ответ 3

Это то, что вы хотите?

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