Method Руководство по документированию методов

В данном руководстве рассматриваются рекомендации по документированию методов для основных классов Ruby и классов стандартной библиотеки.

Цель

Цель при документировании метода — передать самую важную информацию о методе за кратчайшее время. Читатель документации метода должен быстро понять назначение метода и как его использовать. Предоставление слишком малой информации о методе нежелательно, но предоставление неважной или ненужной информации или примеров тоже нежелательно. Используйте свой опыт, чтобы понять, что пользователю метода нужно знать, чтобы правильно использовать метод.

Общая структура

Общая структура документации метода должна быть следующей:

• call-seq (для методов, написанных на C)

• Описание (краткое описание)

• Подробное описание и примеры

• Описание аргументов (при необходимости)

• Крайние случаи и исключения

• Псевдонимы

• Связанные методы (необязательно)

call-seq (для методов, написанных на C)

Для методов, написанных на C, RDoc не может определить, какие аргументы принимает метод, поэтому эти аргументы необходимо документировать, используя call-seq. Вот пример call-seq:

*  call-seq:
*    array.count -> integer
*    array.count(obj) -> integer
*    array.count {|element| ... } -> integer

При создании call-seq, используйте формат

receiver_type.method_name(arguments) {|block_arguments|} -> return_type

Опускайте скобки в тех случаях, когда метод не принимает аргументы, и опускайте блок в тех случаях, когда блок не принимается.

В тех случаях, когда метод может возвращать несколько различных типов, разделяйте типы символом «или». Если метод может возвращать любой тип, используйте «объект». Если метод возвращает получатель, используйте «self».

В тех случаях, когда метод принимает необязательные аргументы, используйте call-seq с необязательным аргументом, если поведение метода при опущении аргумента такое же, как и при передаче аргумента со значением по умолчанию. Например, используйте:

*     obj.respond_to?(symbol, include_all=false) -> true or false

Вместо:

*     obj.respond_to?(symbol) -> true or false
*     obj.respond_to?(symbol, include_all) -> true or false

Однако, как показано выше для Array#count, используйте отдельные строки, если поведение отличается при опущении аргумента.

Опускайте псевдонимы из call-seq.

Описание

Далее следует описание — краткое описание того, что делает метод и почему его стоит использовать. В идеале это должно быть одно предложение, но для более сложных методов может потребоваться целый абзац.

Для Array#count, описание звучит так:

Returns a count of specified elements.

Это отлично, так как кратко и описательно. Избегайте слишком подробного описания в описании, сосредоточьтесь на самой важной информации для читателя.

Подробное описание и примеры

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

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

Добавляйте пример только в том случае, если он предоставляет пользователю дополнительную информацию; не добавляйте пример, если он предоставляет ту же информацию, что и в описании или подробном описании. Цель примеров — не доказать то, что говорится в описании.

Описание аргументов (при необходимости)

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

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

Если есть более одного аргумента или аргумента блока, используйте список определений:

argument_name1

тип и описание

argument_name2

тип и описание

Крайние случаи и исключения

Для крайних случаев методов, таких как необычное использование, кратко упомяните поведение, но не предоставляйте никаких примеров.

Документируйте исключения только если они не очевидны. Например, если ранее вы указали, что тип аргумента должен быть целым числом, вам не нужно документировать, что генерируется TypeError если передано не целое число. Не предоставляйте примеров исключений, если это не обычный случай, например, Hash#fetch, генерирующий KeyError.

Псевдонимы

Укажите псевдонимы в форме: «Array#find_index — это псевдоним для Array#index».

Связанные методы (необязательно)

В некоторых случаях полезно документировать, какие методы связаны с текущим методом. Например, документация для Hash#[] может упоминать Hash#fetch как связанный метод, а Hash#merge может упоминать merge! как связанный метод. Подумайте, какие методы могут быть связаны с текущим методом, и если вы считаете, что это будет полезно для читателя, в конце документации метода добавьте строку, начинающуюся со слов «Связанные: » (например, «Связанные: fetch»). Не указывайте более трёх связанных методов. Если вы считаете, что связанных методов больше трёх, выберите три самых важных и укажите их.

Методы, принимающие несколько типов аргументов

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

Использование языка

Читатели этой документации могут не являться носителями языка English. Документация должна быть написана с учётом этого.

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

При написании документации определите необычные или критические понятия простым языком. Предоставьте ссылки на авторитетные источники или добавьте общее описание в документацию верхнего уровня для класса или модуля.

Форматирование

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

Методы документируются с использованием синтаксиса RDoc. Обратитесь к справке по форматированию с помощью синтаксиса RDoc для получения дополнительной информации.