4

そのため、一般的に使用されるものに対していくつかの拡張メソッドがあり、それらを文書化する際に、XML コメントでタグを一貫して記述する方法がわからないことに気づきました。summary例えば：

    /// <summary>
    ///     Gets a subset of characters from the left-hand side of a string.
    /// </summary>
    public static string Left(this string value, int length)

対。

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

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

問題は、拡張メソッドを文書化するためのガイダンスは何かということです。正式なガイダンスがない場合、皆さんはどのように対処しますか? 投票していない場合は、何かに投票して、私が何かを続けることができますか? 強迫観念的なコントロールフリークとして、この矛盾は私を怒らせています.

4

1 に答える 1

3

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

これは拡張メソッド側から考えるのは少し難しいかもしれませんが、人々が静的メソッドを呼び出している反対側からメソッドを想像すると、それは簡単です。

もう1つ...（MVCのHtmlHelperのように）オブジェクトを必要ではなく慣例から外して拡張していることに気付く場合があります。これは、メソッドがオブジェクトに作用しないため、拡張されているオブジェクトがnullであるかどうかは問題ではないことを意味します。慣例（私は信じています）はオブジェクトがnullのときにスローするthisことですが、メソッドを正常に完了させ、この事実をヘルプに文書化することを好みます（つまり、「...これはnullになる可能性があります」または「...nullはこの引数の有効な値。"）

于 2008-12-31T19:51:09.737 に答える