Программирование на языке Ruby
вернуться

Фултон Хэл
Шрифт:

В листинге 17.1 приведен простой (почти ничего не содержащий) исходный файл. Все определенные в нем методы пусты. Но

RDoc
даже в таком случае формирует симпатичную страницу документации (рис. 17.1).

Листинг 17.1. Простой исходный файл

require ' foo'

# Внешний класс MyClass.

class MyClass

 CONST = 237

 # Внутренний класс MyClass::Alpha...

 class Alpha

# Класс The MyClass::Alpha::Beta...

class Beta

# Метод класса Beta mymeth1.

def mymeth1

end

end

# Метод класса Alpha mymeth2.

def mymeth2

end

 end

 # Инициализировать объект.

 def initialize(a,b,c)

 end

 # Создать объект со значениями по умолчанию

 def self.create

 end

 # и метод экземпляра.

 def do_something

 end

end

Рис. 17.1. Выходной файл, формируемый программой RDoc по исходному тексту в листинге 17.1

В этом разделе мы обсудим еще две полезные функции. Имя каждого метода является ссылкой, при щелчке по которой открывается исходный текст метода. При изучении библиотеки это оказывается исключительно полезно - документация API ссылается на сам код.

Кроме того, когда программа RDoc распознает URL, она помещает в выходной файл гиперссылку. По умолчанию текст гиперссылки совпадает с самим URL, но это можно изменить. Если перед URL поместить в фигурных скобках какой-нибудь описательный текст, то он и станет содержимым ссылки. Если текст состоит из одного слова, фигурные скобки можно опустить.

17.1.1. Простая разметка

Если вы хотите «разукрасить» вывод, то редактировать 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