我来帮你搞定RDoc生成文件和顶级方法文档的问题！

问题出在哪？ #

你的代码注释格式和RDoc的默认行为导致这两个内容没被生成：

• 文件注释的写法不符合RDoc的识别规则，位置也需要调整；
• RDoc默认不会包含顶级方法的文档，需要额外参数开启。

修正步骤 #

1. 调整文件级文档的格式

把文件注释放在文件最开头（任何require或代码之前），用清晰的多行##注释块，RDoc会自动把这个识别为文件的文档：

##
# foo.rb 的文档说明
# 创建日期：09/05/2018
#
# 这个文件包含了Foo类和一个顶级方法foo_method，用于[补充你的文件用途]

require 'stuff'

2. 确保顶级方法被RDoc收录

你的foo_method注释写法是对的，但需要让RDoc不忽略它。运行RDoc时加上--all（缩写-a）参数，这个参数会强制RDoc包含所有顶级方法、属性，而不仅仅是类和模块。

3. 修正后的完整代码示例

##
# foo.rb 的文档说明
# 创建日期：09/05/2018
#
# 这个文件提供了Foo类和一个用于[说明功能]的顶级方法foo_method

require 'stuff'

##
# Foo类的文档
#
# 这个类负责[描述Foo类的职责]
class Foo
  # 类内部实现
end

##
# 顶级方法foo_method的文档
#
# 这个方法用于[描述方法功能]
# @return [返回值类型] 描述返回值的含义
def foo_method
  # 方法实现
end

4. 运行正确的RDoc命令

在终端执行：

rdoc -a foo.rb

生成的文档效果 #

运行后，你会在生成的HTML文档里看到：

• 在「Files」页面下有foo.rb的完整文档；
• Foo类的文档（和之前一样）；
• 在「Top Level Namespace」或者「Methods」板块下，能找到foo_method的文档（具体位置取决于你的RDoc版本）。

如果还是有问题，可以检查下你的RDoc版本，建议使用较新的版本（比如3.x以上），旧版本对顶级元素的支持可能有局限。

内容的提问来源于stack exchange，提问作者Astariul