Если вы хотите «разукрасить» вывод, то редактировать HTML-файлы вручную необязательно. На самом деле даже нежелательно, так как при повторной генерации документации ваши изменения будут затерты.
RDoc располагает собственным механизмом разметки, поэтому можно включать в исходный текст информацию о форматировании. Правила языка разметки выбраны так, что текст в редакторе выглядит «естественно», но вместе с тем может быть легко преобразован в HTML.
В листинге 17.2 приведено несколько примеров разметки; дополнительную информацию ищите в книге «Programming Ruby» или в документации по
RDoc
. На рис. 17.2 показано, во что преобразуется текст в листинге 17.2 (нижний фрейм).
Листинг 17.2. Пример разметки для RDoc
# This block comment will be detected and
# 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:
. Например, если в самом тексте употребляются ничего не значащие имена