Cómo documentar adecuadamente un método de extensión

Question

Por lo tanto, tengo algunos métodos de extensión, para cosas de uso común, y al documentarlos, se me ocurre que no tengo ni idea sobre cómo escribir constantemente el resumen etiqueta en los comentarios XML. Por ejemplo:

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

Entonces, el problema parece ser que no sé cómo referirme constantemente a ese molesto parámetro este . Además, no sé cómo indicar claramente que este es un método de extensión (ya que no estoy seguro de que Sandcastle y otras herramientas los hayan alcanzado todavía y puedan anotar automáticamente la documentación para mostrarlo); Odiaría tener que arrancar toda esa documentación manual más tarde.

Entonces, la pregunta es, ¿qué orientación hay para documentar los métodos de extensión? Si no hay una guía formal, ¿cómo lo manejan todos? Si no lo hemos hecho, ¿podemos votar sobre algo para que tenga algo para seguir? Como un obseso obsesivo con el control compulsivo, esta inconsistencia me está volviendo loco.

Answer 1

Los lenguajes .NET que no admiten los métodos de extensión requerirán que los usuarios llamen al método directamente y pasen el objeto que se habría extendido. Por lo tanto, es importante documentar este parámetro y describir exactamente por qué se necesita y cómo el método actuará sobre él.

Esto puede ser un poco difícil de pensar desde el lado del método de extensión, pero si visualiza el método desde el otro lado, donde las personas están llamando a un método estático, es más fácil.

Otra cosa ... A veces, puedes encontrarte (como HtmlHelper en MVC) donde extiendes un objeto fuera de convención en lugar de necesidad. Esto significa que no importa si el objeto que se está extendiendo es nulo o no porque el método no actúa sobre él. Si bien la convención (creo) es lanzar cuando el objeto este es nulo, prefiero dejar que el método se complete normalmente y documentar este hecho en la ayuda (es decir, " ... Esto puede ser null " o " ... null es un valor válido para este argumento. ")