Хэл Фултон - Программирование на языке Ruby
# included in the rdoc output.
#
=begin rdoc
So will this one. Note the presence of the "rdoc"
tag on the begin-line. This is to distinguish the
block comment as belonging to rdoc as opposed to
being read by some other tool.
=end
=begin rdoc
Here are some formatting tricks.
Boldface, italics, and "code" (without spaces):
This is *bold*, this is _italic_, and this is +code+.
With spaces:
This is a bold phrase. Have you read Intruder
in the Dust? Don't forget to require thread
at the top.
= First level heading
== Second level heading
=== Third level heading
Here's a horizontal rule:
---
Here's a list:
- item one
- item two
- 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 инструментах создания пакетов и развертывания.
17.2.1. Библиотека setup.rb
Автором библиотеки setup.rb является Минеро Аоки (Minero Aoki). Он же разработал библиотеку install.rb, которая сейчас используется реже.
Кто-то скажет, что по мере развития системы RubyGems все это становится не актуальным. А кто-то возразит, что у gem-пакетов есть свои проблемы (технические, политические и пр.). А кто-то считает, что «добропорядочный гражданин» должен включать setup.rb даже в gem-пакет (упрощая задачу перепакетирования, например для создания Linux-дистрибутива). Решать вам.
Половина дела будет сделана, если вы скопируете все файлы в нужные места. Вы должны организовать свой архив простым и разумным образом (создав каталоги с предопределенными именами).
Предположим, что дистрибутив содержит единственный пакет в архиве (наиболее распространенный случай). Тогда дерево каталогов организуется примерно так (причем файл setup.rb помещается на верхний уровень).
top_level/
setup.rb
metaconfig (необязательно)
lib/
ext/
myext/
bin/
data/
conf/
man/
test/
Пустые каталоги можно опускать. Ниже описано назначение каждого каталога:
• lib —программы на Ruby;
• ext — расширения Ruby (написанные на С);
• myext — имя расширения (на том же уровне могут располагаться и другие расширения); в каталоге каждого расширения должен находиться либо файл extconf.rb, либо MANIFEST;
• bin — команды;
• data — файлы данных;
• conf — конфигурационные файлы;
• man — страницы руководства;
• test — автономные тесты и другие тестовые программы.
В общем случае эти файлы никак не обрабатываются, а просто копируются в нужное место. Но для специализированной настройки предусмотрены места подключения к каждому этапу процесса.
Три основных этапа — это config, setup и install, вызываемые пользователем именно в таком порядке (на последнем шаге могут потребоваться полномочия root или, по крайней мере, выполнение sudo).
Для подключения к этапу вы просто помещаете в нужный каталог написанную на Ruby программу с известным именем. Например, если необходимо перед обработкой сделать что-то нестандартное с файлом lib/foobar, следует создать файл lib/foobar/pre-setup.rb и поместить в него произвольный код.
Имя файла формируется следующим образом: префикс pre или post, дефис, имя задачи. Определены следующие имена задач: config, setup, install, test, clean и dist-clean.
В библиотеке setup.rb есть понятия каталога исходных файлов, или исходного каталога (source directory) и каталога объектных файлов, или объектного каталога (object directory). Как правило, вы должны читать из исходного каталога и записывать в текущий каталог.
Существует «API для подключения» (hook API), упрощающий решение ряда задач. Приведем некоторые определенные в нем методы:
• get_config_key(key) — принимает в качестве параметра ключ и возвращает ассоциированное с ним значение (например, get_config('prefix') возвращает путь, определенный с помощью конфигурационного параметра --prefix);
• set_config_key(key, val) — устанавливает значение конфигурационного параметра;
• config_key(key) — то же, что get_config_key;
• curr_srcdir — текущий исходный каталог;
• curr_objdir — текущий объектный каталог;
• srcfiles(rel_path=".") — список всех файлов в каталоге с путем rel_path (относительно текущего исходного каталога).
На верхнем уровне может находиться файл metaconfig. Если он есть, то в нем задаются некоторые глобальные конфигурационные параметры. Для этой цели имеется специальный «metaconfig API» — небольшой набор вспомогательных методов, в частности:
• add_path_config(confname, default, description) — определяет конфигурационный параметр, являющийся путем; задаются имя и значение по умолчанию. При вызове с флагом --help эта информация печатается;
• add_bool_config(confname, default, description) — аналог add_path_config, но описывается булевский параметр.
