Есть ли хорошая и надежная ссылка на правильный синтаксис RDoc?

Question

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

1. Как документировать методы класса и их параметры
2. Как документировать, что делает класс или метод класса.

Answer 1

Официальный пример rdoc можно найти здесь, с его источником GitHub.

Документация на http://rdoc.rubyforge.org/RDoc.html представляется более полной, чем версия на http://rdoc.sourceforge.net/doc/index.html (которая, кстати, имеет дату изменения 2003 года).

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

File.atime (file_name) => время

Возвращает время последнего доступа к названному файлу как объекту времени).

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.

Answer 2

Так как RubyForge был удален, вот новая ссылка:

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

Answer 3

ИМХО, лучшим официальным справочником по разметке RDoc является MarkupReference вместе с его исходным кодом на Github .