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

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

Цель

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

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

Общие рекомендации

• Помните, что читатель может не быть носителем языка английского.

• Пишите короткие декларативные или императивные предложения.

• Группируйте предложения в (желательно короткие) абзацы, каждый из которых охватывает одну тему.

• Организуйте материал с помощью заголовков.

• Ссылайтесь на авторитетные и соответствующие источники, используя ссылки.

• Используйте простые времена глаголов: настоящее простое, прошедшее простое, будущее простое.

• Используйте простую структуру предложений, а не сложные или составные.

• Избегайте:

  • Чрезмерных фраз, разделённых запятыми; рассмотрите использование списков.

  • Идиом и ссылок, специфичных для культуры.

  • Чрезмерного использования заголовков.

RDoc

Ruby документируется с помощью RDoc. Для получения информации о синтаксисе и функциях RDoc см. ссылку на руководство по разметке RDoc.

Вывод из irb

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

Для примера кода, включающего irb вывод, рассмотрите выравнивание # => ... в последовательных строках. Выравнивание иногда может улучшить читаемость:

a = [1, 2, 3] #=> [1, 2, 3]
a.shuffle!    #=> [2, 3, 1]
a             #=> [2, 3, 1]

Заголовки

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

Пустые строки

Пустая строка начинает новый абзац.

Блок кода или список должны предшествовать и следовать за пустой строкой. Это не нужно для HTML-вывода, но помогает в ri выводе.

Автоматическое связывание

В общем случае автоматическое связывание RDoc не должно подавляться. Например, мы должны написать Array, а не \Array.

Мы можем рассмотреть возможность подавления, когда:

• Слово в вопросе не относится к объекту Ruby (например, некоторые использования Class или English).

• Ссылка относится к текущей странице документации класса (например, Array в документации для класса Array).

• Такая же ссылка повторяется много раз (например, RDoc на этой странице).

Документирование классов и модулей

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

• Резюме

• Общие случаи использования с примерами

• Резюме «Что здесь» (необязательно)

Резюме

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

Общие случаи использования

Покажите общие случаи использования класса или модуля. В зависимости от класса или модуля этот раздел может значительно отличаться по длине и сложности.

Резюме «Что здесь»

Документация класса или модуля может включать раздел «Что здесь».

Руководящие принципы:

• Название раздела — What's Here.

• Рассмотрите возможность перечисления родительского класса и любых включенных модулей; рассмотрите ссылки на их разделы «Что здесь», если они существуют.

• Перечислите методы в виде меток списка.

• Метка каждой записи — имя метода; если метод имеет псевдонимы, включите их с «базовым» методом и не перечисляйте их отдельно.

• Проверьте сгенерированную документацию, чтобы определить, распознал ли RDoc метод и создал ссылку на него; если нет, вручную добавьте ссылку.

• Описание каждой записи — краткое резюме метода в одну строку.

• Сохраняйте описание коротким.

• Если имеется больше записей, рассмотрите возможность объединения их в подраздёлы с заголовками.

• Если таких подраздёлов более нескольких, рассмотрите возможность добавления оглавления сразу под основным заголовком раздела.

Документирование методов

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

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

• Последовательность вызова (для методов, написанных на C).

• Резюме (краткое описание).

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

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

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

• Псевдонимы.

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

Последовательность вызова (для методов, написанных на C)

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

Для методов, написанных на C, RDoc не может определить, какие аргументы принимает метод, поэтому их необходимо документировать с помощью директивы RDoc :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».

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

*     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, но упоминайте их в конце (см. ниже).

Блок call-seq должен иметь {|x| ... }, а не {|x| block } или {|x| code }.

Вывод call-seq должен:

• Иметь self, а не receiver или array.

• Начинаться с new_ только в том случае, если выходной объект является новой экземпляром класса получателя, чтобы подчеркнуть, что выходной объект не является self.

Резюме

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

Для Array#count, резюме такое:

Returns a count of specified elements.

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

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

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

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

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

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

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

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

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

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

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

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

Псевдонимы

Укажите псевдонимы в форме

Array#find_index is an alias for Array#index.

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

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

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

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