Чтение онлайн

Если вы хотите «разукрасить» вывод, то редактировать HTML-файлы вручную необязательно. На самом деле даже нежелательно, так как при повторной генерации документации ваши изменения будут затерты.

RDoc располагает собственным механизмом разметки, поэтому можно включать в исходный текст информацию о форматировании. Правила языка разметки выбраны так, что текст в редакторе выглядит «естественно», но вместе с тем может быть легко преобразован в HTML.

В листинге 17.2 приведено несколько примеров разметки; дополнительную информацию ищите в книге «Programming Ruby» или в документации по

. На рис. 17.2 показано, во что преобразуется текст в листинге 17.2 (нижний фрейм).

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

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

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

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

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

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

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

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

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

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

Здесь класс

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

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

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

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

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

Модификатор

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

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

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