Come documentare correttamente un metodo di estensione

Question

Quindi, ho alcuni metodi di estensione, per cose comunemente usate, e nel documentarli, mi è venuto in mente che non ho nessuna idea come scrivere costantemente il sommario tag nei commenti XML. Ad esempio:

    /// <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)

Quindi, il problema sembra essere che non so come fare costantemente riferimento a quel fastidioso questo parametro. Inoltre, non so come indicare chiaramente che questo è un metodo di estensione (poiché non sono sicuro che Sandcastle e altri strumenti li abbiano ancora raggiunti e possano annotare automaticamente la documentazione per mostrarlo); Odierei dover strappare tutta quella documentazione manuale più tardi.

Quindi la domanda è: quali indicazioni ci sono per documentare i metodi di estensione? Se non esiste una guida formale, come la gestite tutti? In caso contrario, possiamo votare qualcosa in modo che io abbia qualcosa da fare? Essendo un maniaco ossessivo del controllo compulsivo, questa incoerenza mi sta facendo impazzire.

Answer 1

I linguaggi .NET che non supportano i metodi di estensione richiederanno agli utenti di chiamare direttamente il metodo e passare l'oggetto che sarebbe stato esteso. Pertanto è importante documentare questo parametro e descrivere esattamente perché è necessario e come il metodo agirà su di esso.

Questo può essere un po 'difficile da pensare dal lato del metodo di estensione, ma se immagini il metodo dall'altro lato, in cui le persone chiamano un metodo statico, è più facile.

Un'altra cosa ... A volte potresti trovarti (come HtmlHelper in MVC) in cui stai estendendo un oggetto fuori dalla convenzione piuttosto che dalla necessità. Ciò significa che non importa se l'oggetto che viene esteso è nullo o meno perché il metodo non agisce su di esso. Mentre la convenzione (credo) debba essere lanciata quando l'oggetto this è nullo, preferisco lasciare che il metodo si completi normalmente e documentare questo fatto nella guida (cioè, " ... Questo può essere null " oppure " ... null è un valore valido per questo argomento. ")