我正在为正确的 RDoc 语法寻找一个好的、可靠的参考。建议?我似乎找不到任何清楚显示的内容:
- 如何记录类方法及其参数
- 如何记录类或类方法的作用。
可以在此处找到官方 rdoc 示例及其GitHub 源代码。
rdoc.rubyforge.org上的文档似乎比rdoc.sourceforge.net上的版本更完整(顺便说一下,它的修改日期是 2003 年)。
此外,还有大量示例资源:Ruby 核心和 stdlib 文档。例如,看一下 class 中的一个类File
方法:
File.atime(file_name) => 时间
将命名文件的最后访问时间作为 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。