métodos Documentar sobrecargados con el mismo XML comentarios

Question

decir que tengo este constructor:

/// <summary> 
/// Example comment. 
/// </summary> 
public SftpConnection(string host, string username, 
    string password, int port) {...} 

que tiene estas sobrecargas:

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) { } 

y en realidad, el comentario XML es bastante grande, con param, example y exception elementos y así sucesivamente.

¿Hay alguna forma de agregar un comentario XML especial a las sobrecargas, de modo que utilicen los mismos comentarios para no tener que copiar y pegar todos los enormes comentarios originales?

Estoy pensando algo así como: <use cref="SftpConnection(string,string,string,int)" /> que no funciona, por supuesto.

Conozco el elemento include, pero me da la impresión de que lee los comentarios de un archivo XML, que no quiero, quiero que el comentario siga siendo visible en el código, pero solo una vez.

Gracias :-)

Answer 1

No se puede hacer esto. Me parece molesto también.

Sin embargo, puede aliviar el problema utilizando valores de parámetros predeterminados en lugar de muchas sobrecargas. En lugar de:

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) 

Puede haber sólo uno solo:

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

Esto tiene múltiples ventajas:

• sólo necesitan un comentario XML. Todo el punto de mi respuesta. ☺

• Los usuarios de Visual Studio pueden ver instantáneamente que el valor predeterminado para port es 22. Con las sobrecargas, esto no es obvio; tienes que mencionarlo específicamente en la documentación.

• Alientas indirectamente el código del cliente para que sea más legible al alentar el uso de parámetros con nombre (por ejemplo, port: 2222 en lugar de solo 2222, que es menos claro).

Y la mayor parte de esto es que el uso de valores por defecto hace no eliminar la posibilidad de tener todavía varias sobrecargas si los necesita. Los ejemplos típicos en los que desee sobrecargas con valores por defecto podría ser algo así como ...

ReadFrom(string filename, ReaderOptions options = null) 
ReadFrom(Stream stream, ReaderOptions options = null) 
ReadFrom(byte[] rawData, ReaderOptions options = null) 

En estos casos, yo diría que los comentarios XML en realidad debería ser diferente.

Answer 2

¿Esto es lo que quieres?

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

Answer 3

Una media solución es la etiqueta <overloads></overloads>.Si bien no resuelve el problema con <summary/>, proporciona documentación que se muestra en cualquier lugar donde todas las sobrecargas estén enumeradas como un grupo, incluidos IntelliSense y SandCastle.