Comment documenter correctement une méthode d'extension

Question

J'ai donc quelques méthodes d'extension, pour les éléments couramment utilisés, et en les documentant, je me suis rendu compte que je n'ai aucune idée comment écrire de manière cohérente le summary balise dans les commentaires XML. 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)

vs.

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

Donc, le problème semble être que je ne sais pas comment faire systématiquement référence à ce paramètre this . De plus, je ne sais pas comment indiquer clairement qu'il s'agit d'une méthode d'extension (étant donné que je ne suis pas sûr que Sandcastle et d'autres outils l'ont déjà rattrapé et qu'il peut annoter automatiquement la documentation pour la montrer); Je détesterais devoir extraire toute cette documentation manuelle plus tard.

La question est donc de savoir quelles sont les directives pour documenter les méthodes d’extension. S'il n'y a pas d'orientation formelle, comment vous y prenez-vous tous? Si nous ne l'avons pas fait, pouvons-nous voter sur quelque chose pour que je puisse continuer? En tant que maniaque obsessionnel du contrôle compulsif, cette incohérence me rend fou.

Answer 1

Les langages .NET qui ne prennent pas en charge les méthodes d'extension nécessiteront 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 agira en conséquence.

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 retrouver (comme HtmlHelper dans MVC) où vous étendez un objet en dehors de la convention plutôt que de la nécessité. Cela signifie que peu importe si l'objet en cours d'extension est nul ou non, car la méthode n'agit pas dessus. Bien que la convention (je crois) consiste à lancer lorsque l'objet cet est nul, je préfère laisser la méthode se terminer normalement et consigner ce fait dans l'aide (c'est-à-dire, "... cela peut être null "ou" ... null est une valeur valide pour cet argument. ")