Книга: Программирование на языке Ruby

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

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

Оглавление книги