c# - fuente - generar documentacion visual studio 2017

Documentación de métodos sobrecargados con los mismos comentarios XML.

Question

Digamos 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 elementos de param , example y exception , y así sucesivamente.

¿Hay alguna forma de agregar un comentario especial de XML a las sobrecargas, de manera que usen exactamente los mismos comentarios para que no tenga que copiar y pegar todo, enormes comentarios originales?

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

Soy consciente del elemento de include , pero me da la impresión de que en su lugar 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

¿Es esto lo que quieres?

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

Answer 2

Realmente no puedes hacer esto. Lo encuentro molesto también.

Sin embargo, puede solucionar 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)

Puedes tener solo uno:

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

Esto tiene múltiples ventajas:

• Necesita solo un comentario XML El punto central de mi respuesta. ☺

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

• Usted alienta indirectamente a que el código del cliente sea más legible al fomentar el uso de parámetros con nombre (por ejemplo, port: 2222 lugar de solo 2222 , lo que es menos claro).

Y lo mejor de esto es que el uso de valores predeterminados no elimina la posibilidad de tener varias sobrecargas si las necesita. Los ejemplos típicos en los que desea sobrecargas con valores predeterminados podrían ser algo como ...

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

En estos casos, diría que los comentarios XML deberían ser diferentes.

Answer 3

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