Como documentar corretamente um método de extensão

Question

Então, eu tenho alguns métodos de extensão, para o material comumente usado, e em documentar-los, me ocorreu que eu tenho idéia como escrever de forma consistente a tag summary nos comentários XML. Por exemplo:

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

Assim, o problema parece ser que eu não sei como se referir de forma consistente a esse parâmetro traquinas this. Além disso, eu não sei como indicam claramente que este é um método de extensão (desde que eu não estou certo de que Sandcastle e outras ferramentas de ter apanhado a eles ainda, e pode anotar automaticamente a documentação para mostrá-lo); Eu odiaria ter de rasgar tudo o que documentação Manual mais tarde.

Portanto, a questão é, o que a orientação está lá para documentar métodos de extensão? Se não há nenhuma orientação formal, como você tudo lidar com isso? Se não temos, podemos votar em algo, então eu tenho algo para ir em frente? Como um maníaco por controle obsessivo compulsivo, essa inconsistência está me deixando louco.

Answer 1

.NET idiomas que não suportam métodos de extensão exigirá que os usuários chamar o método diretamente e passar o objeto que teria sido estendido. Por isso, é importante documentar esse parâmetro e descrever exatamente por isso que é necessário e como o método vai agir sobre ele.

Este pode ser um pouco difícil pensar de um lado o método de extensão, mas se você imaginar o método do outro lado, onde as pessoas estão chamando um método estático, é mais fácil.

Uma outra coisa ... Às vezes você pode encontrar-se (como o HtmlHelper no MVC), onde você está estendendo um objeto fora do convenção em vez de necessidade. Isto significa que não importa se o objeto que está sendo estendido é nulo ou não, porque o método não agir sobre ele. Enquanto a convenção (creio eu) é jogar quando o objeto this é nulo, eu prefiro deixar o método concluída normalmente e documentar esse fato na ajuda (ou seja, "... Isto pode ser nulo" ou" ... nula é um valor válido para este argumento. ")