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

Question

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

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

Answer 1

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

Документация Rdoc.rubyforge.org. кажется, более полным, чем версия в rdoc.sourceforge.net. (который кстати имеет модифицированную дату 2003 года).

Кроме того, существует отличный источник примеров: документация Ruby Core и 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: Позволяет заменить имя и параметры метода с помощью текста вашего выбора, что очень полезно для методов классов. Он также показывает, как вы можете отображать пример кода в шрифте моноспециста, отставая на него, аналогично разметку.

Answer 2

С RubyForge был на пенсии, вот новая ссылка:

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