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

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

27 голосов
/ 08 сентября 2010

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

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

Спасибо: -)

Ответы [ 3 ]

19 голосов
/ 08 сентября 2010

Вы не можете этого сделать. Я тоже нахожу это раздражающим.

Однако вы можете решить проблему, используя значения параметров по умолчанию вместо множества перегрузок. Вместо: 

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 на самом деле должны отличаться.

4 голосов
/ 03 октября 2012

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

2 голосов
/ 08 сентября 2010

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

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