Comment documenter correctement une méthode d'extension

Question

Donc, j'ai quelques méthodes d'extension, pour la substance utilisée, et les documenter, il est à moi que je aucune idée comment écrire systématiquement l'étiquette summary dans le fichier XML commentaires. Par exemple:

/// <summary> 
    ///  Gets a subset of characters from the left-hand side of a string. 
    /// </summary> 
    public static string Left(this string value, int length) 

contre

/// <summary> 
    ///  Gets the name of the month for this date. 
    /// </summary> 
    public static string MonthName(this DateTime value) 

Ainsi, le problème semble être que je ne sais pas comment se référer constamment à ce paramètre this embêtants. De plus, je ne sais pas comment indiquer clairement qu'il s'agit d'une méthode d'extension (puisque je ne suis pas certain que Sandcastle et d'autres outils les aient déjà rattrapés et puissent automatiquement annoter la documentation pour la montrer); Je détesterais avoir à déchirer toute cette documentation manuelle plus tard. Donc, la question est, quelle orientation est là pour documenter les méthodes d'extension? S'il n'y a pas de directives formelles, comment gérez-vous tout cela? Si ce n'est pas le cas, pouvons-nous voter sur quelque chose afin d'avoir quelque chose à faire? En tant que maniaque du contrôle compulsif obsessionnel, cette incohérence me rend fou.

Answer 1

Les langages NET qui ne supportent pas les méthodes d'extension nécessitent que les utilisateurs appellent directement la méthode et transmettent l'objet qui aurait été étendu. Par conséquent, il est important de documenter ce paramètre et de décrire exactement pourquoi il est nécessaire et comment la méthode va agir sur lui.

Cela peut être un peu difficile à penser du côté de la méthode d'extension, mais si vous envisagez la méthode de l'autre côté, où les gens appellent une méthode statique, c'est plus facile.

Une autre chose ... Parfois vous pourriez vous trouver (comme le HtmlHelper dans MVC) où vous étendez un objet sur convention plutôt que sur la nécessité. Cela signifie que cela n'a pas d'importance si l'objet qui est en cours d'extension est nul ou non, car la méthode n'agit pas dessus. Alors que la convention (je crois) est de lancer quand l'objet this est nul, je préfère laisser la méthode se terminer normalement et documenter ce fait dans l'aide (ie, "... Cela peut être nul" ou "... null est une valeur valide pour cet argument. ")