Чи є хороший, надійний довідник для правильного синтаксису RDoc?

Я шукаю хороший, надійний довідник для правильного синтаксису RDoc. Рекомендації? Здається, я не можу знайти нічого, що чітко показує:

1. Як документувати методи класу та їх параметри
2. Як задокументувати те, що робить клас або метод класу.

Офіційний приклад rdoc можна знайти тут із джерелом GitHub .

Документація на rdoc.rubyforge.org видається більш повною, ніж версія на rdoc.sourceforge.net (яка, до речі, має дату модифікації 2003 року).

Крім того, є чудове джерело прикладів: ядро ​​Ruby та документація stdlib. Наприклад, погляньте на один із методів класу з Fileкласу :

File.atime (ім'я_файла) => час

Повертає останній час доступу для названого файлу як об'єкта Time).

File.atime("testfile") #=> Wed Apr 09 08:51:48 CDT 2003

Ви можете переглянути оригінальний вихідний код, включаючи розмітку RDoc, натиснувши перший рядок (на фактичній сторінці RDoc, а не в цитаті, яку я включив у цю відповідь). У цьому випадку метод був реалізований на мові C, але форматування RDoc таке саме, як якщо б воно було реалізовано в Ruby:

/*
 *  call-seq:
 *     File.atime(file_name)  =>  time
 *  
 *  Returns the last access time for the named file as a Time object).
 *     
 *     File.atime("testfile")   #=> Wed Apr 09 08:51:48 CDT 2003
 *     
 */

З цього видно, що call-seq:дозволяє замінити назву методу та параметри на текст, який ви обрали, що дуже корисно для методів класу. Він також показує, як ви можете відобразити приклад коду моноширинним шрифтом, відступивши його, подібно до Markdown.

Оскільки RubyForge вийшов на пенсію , ось нове посилання:

http://ruby-doc.org/stdlib-2.5.1/libdoc/rdoc/rdoc/RDoc/Markup.html