Как правильно документировать метод расширения - PullRequest
Новая
       19

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

4 голосов
/ 31 декабря 2008

Итак, у меня есть несколько методов расширения для часто используемых вещей, и при их документировании мне пришло в голову, что я не знаю , как последовательно писать тег 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 и другие инструменты его уже догнали и могут автоматически аннотировать документацию, чтобы показать его); Я бы не хотел вырывать всю эту ручную документацию позже.

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

1 Ответ

2 голосов
/ 31 декабря 2008

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

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

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

...