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» или в любом онлайновом справочном руководстве.