Программирование на языке Ruby
вернуться

Фултон Хэл
Шрифт:

– item three

=end

=begin

This block comment is untagged and will not show up in

rdoc output. Also, I'm not putting blank lines between

the comments, as this will terminate the comments until

some real program source is seen. If this comment had

been before the previous one, processing would have

stopped here until program text appeared.

=end

Рис. 17.2. Результат работы RDoc для примера из листинга 17.2

В листинге 17.2 приведено несколько правил разбора документов, принятых в

RDoc
. Не все они интуитивно очевидны. Считается, что пустые строки завершают блок комментариев, даже если вслед за пустой строкой сразу идет еще один такой блок.

Внутри блока комментариев, начинающегося со знака

#
, можно отключить копирование текста в выходной файл, вставив строку
#--
(а следующая такая строка вновь включает копирование). Ведь не все комментарии должны быть частью пользовательской документации.

Отметим еще, что если используются маркеры

=begin
и
=end
, то после
=begin
должен находиться тег
rdoc
, иначе
RDoc
проигнорирует весь блок целиком. Это сделано во избежание конфликтов с более старыми инструментами, в которых такие блоки активно использовались.

17.1.2. Более сложное форматирование

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

Одним из самых важных является тег

:nodoc:
, отключающий вывод документации для определенного фрагмента. Обычно он ставится в той же строке, где начинается определение класса или метода.

class Alpha # :nodoc:

 class Beta

# ...

 end

 # ...

end

Здесь класс

Alpha
не будет документироваться. Однако тег
:nodoc:
не является рекурсивным — класс
Beta
документируется. Если желательно рекурсивное

поведение, укажите

:nodoc: all
. В следующем примере игнорируются оба класса
Gamma
и
Delta
:

class Alpha # :nodoc: all

 class Beta

# ...

 end

 # ...

end

Имеется также модификатор

:doc:
с прямо противоположным смыслом. Он включает документацию для фрагментов, которые иначе не были бы документированы.

Модификатор

:notnew:
специальный; он предотвращает документирование метода
new
(на основе существующего метода
initialize
).

Если вы хотите дать осмысленные имена параметрам

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

def iterate # :yields: element, index

 # ...

 yield x, i

end

Некоторые теги используются только внутри блока комментариев, например:

• 

:include:
— включить содержимое указанного файла в документацию. При этом будут сформированы подходящие отступы;

• 

:titlе:
— задать заголовок документа;

• 

:main:
— задать начальную страницу документации.

Дополнительную информацию вы найдете в книге «Programming Ruby» или в любом онлайновом справочном руководстве.

17.2. Установка и подготовка пакета

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

К счастью, в Ruby все это не так болезненно, как в некоторых других языках и средах. Вы обязательно должны знать о библиотеке

setup
и системе RubyGems — «родных» для Ruby инструментах создания пакетов и развертывания.