Documenter méthodes surchargées avec les mêmes commentaires XML

Question

Dire que j'ai ce constructeur:

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

qui a ces surcharges:

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

et en réalité, le commentaire XML est assez grand, avec param, example et exception éléments et ainsi de suite. Y a-t-il un moyen d'ajouter un doublon de commentaire XML spécial aux surcharges, de sorte qu'ils utilisent exactement les mêmes commentaires de sorte que je n'ai pas besoin de copier-coller les entiers, énormes commentaires originaux?

Je pense quelque chose comme: <use cref="SftpConnection(string,string,string,int)" /> qui ne fonctionne pas bien sûr.

Je suis au courant de l'élément include, mais je l'impression qu'il lit au lieu des commentaires à partir d'un fichier XML, que je ne veux pas - je veux que le commentaire soit encore visible dans le code, mais une seule fois.

Merci :-)

Answer 1

Vous ne pouvez pas vraiment faire cela. Je trouve ça agaçant aussi. Toutefois, vous pouvez résoudre le problème en utilisant des valeurs de paramètre par défaut plutôt que de nombreuses surcharges. Au lieu 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) 

Vous pouvez avoir juste un seul:

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

Cela a plusieurs avantages:

• Besoin d'un seul commentaire XML. Tout le point de ma réponse. Users

• Les utilisateurs de Visual Studio peuvent instantanément voir que la valeur par défaut pour port est 22. Avec les surcharges, cela n'est pas évident; vous devez le mentionner spécifiquement dans la documentation.

• Vous indirectement code encourages client pour devenir plus lisible en encourageant l'utilisation des paramètres nommés (par exemple port: 2222 au lieu de simplement 2222, qui est moins clair).

Et la plus grande partie à ce sujet est que l'utilisation de valeurs par défaut ne pas supprimer la possibilité d'avoir encore plusieurs si vous les surcharges besoin. Des exemples typiques où vous voulez avec des valeurs surcharges par défaut pourrait être quelque chose comme ...

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

Dans ce cas, je dirais les commentaires XML devraient effectivement être différents.

Answer 2

Est-ce ce que vous voulez?

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

Answer 3

Une demi-solution est l'étiquette <overloads></overloads>.Bien qu'il ne résout pas le problème avec <summary/>, il fournit une documentation qui s'affiche partout où toutes les surcharges sont répertoriées en tant que groupe, y compris IntelliSense et SandCastle.