Как правильно задокументировать метод расширения

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)

против.

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

Итак, проблема, похоже, в том, что я не знаю, как последовательно ссылаться на это надоедливое this параметр.Кроме того, я не знаю, как четко указать, что это метод расширения (поскольку я не уверен, что Sandcastle и другие инструменты уже освоили их и могут автоматически комментировать документацию, чтобы показать это);Мне бы не хотелось позже удалять всю эту документацию по руководству.

Итак, вопрос в том, какие существуют рекомендации по документированию методов расширения?Если нет официального руководства, как вы все с этим справляетесь?Если мы этого не сделали, можем ли мы проголосовать за что-нибудь, чтобы мне было на что опереться?Как одержимый манией контроля, эта непоследовательность сводит меня с ума.

Answer 1

Языки .NET, которые не поддерживают методы расширения, потребуют, чтобы пользователи вызывали метод напрямую и передавали объект, который был бы расширен.Поэтому важно задокументировать этот параметр и точно описать, зачем он нужен и как метод будет воздействовать на него.

Об этом может быть немного сложно думать со стороны метода расширения, но если вы представите метод с другой стороны, где люди вызывают статический метод, все будет проще.

И еще кое-что...Иногда вы можете обнаружить, что сами (например, HtmlHelper в MVC) расширяете объект из конвенция скорее, чем необходимость.Это означает, что не имеет значения, является ли расширяемый объект null или нет, потому что метод не воздействует на него.В то время как соглашение (я полагаю) состоит в том, чтобы выбрасывать, когда this object равен null, я предпочитаю позволить методу завершиться нормально и задокументировать этот факт в справке (т.е. "...Это может быть нулевое значение "или "...null - это допустимое значение для этого аргумента ".)