拡張メソッドを適切に文書化する方法

Question

だから、私は一般的に使用されるもののためにいくつかの拡張メソッドを持っていますが、それらを文書化する際に、 summary XMLコメント内のタグ。例：

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

したがって、問題は、その厄介な this パラメーターを一貫して参照する方法がわからないことです。さらに、これが拡張方法であることを明確に示す方法がわかりません（Sandcastleや他のツールがまだそれらに追いついていないので、ドキュメントに自動的に注釈を付けて表示できるため）。後でマニュアルのドキュメントをすべてリッピングするのは嫌です。

質問は、拡張メソッドを文書化するためのガイダンスは何ですか？正式なガイダンスがない場合、どのようにそれを処理しますか？そうでない場合は、何かに投票することができますか？強迫観念の強迫観念のフリークとして、この矛盾は私を怒らせています。

Answer 1

拡張メソッドをサポートしない

.NET言語では、ユーザーがメソッドを直接呼び出して、拡張されたオブジェクトを渡す必要があります。したがって、このパラメーターを文書化し、それが必要な理由とメソッドがそれにどのように作用するかを正確に記述することが重要です。

これは拡張メソッド側から考えるのは少し難しいかもしれませんが、静的メソッドを呼び出している他の側からメソッドを構想すると、簡単になります。

もう1つ...必要ではなく慣習からオブジェクトを拡張している（MVCのHtmlHelperなど）場合があります。これは、メソッドがアクションを実行しないため、拡張されるオブジェクトがnullであるかどうかは関係ないことを意味します。慣例では（ this オブジェクトがnullの場合にスローする）ですが、メソッドを正常に完了させ、この事実をヘルプに記録することをお勧めします（つまり、＆quot; ... null＆quot;または＆quot; ... nullはこの引数の有効な値です。＆quot;）